@sweny-ai/core 0.1.184 → 0.1.186

package/dist/cli/run-answers.js

@@ -0,0 +1,451 @@
+/**
+ * What a run answered, kept so the next run can say what changed.
+ *
+ * `sweny workflow run` saves `.sweny/runs/<run-id>/answers.json` beside the
+ * output.md: each successful node's DECLARED output fields (the node's
+ * `output` schema is the contract; with no schema, only a string `summary`).
+ * Local only, mode 0600, redacted with the run journal's redactor before
+ * anything is stored. The run record itself (run-history.ts) stays metadata
+ * only; answers live in their own file so that contract is untouched.
+ *
+ * Everything under `.sweny/runs/` is writable by an agent, so it is untrusted:
+ * ids are validated against the generator's pattern before any path is built,
+ * the embedded id must match the one asked for, and the PUBLIC line (PR
+ * comment, step summary) carries only the current workflow's own id and
+ * integer counts, never text read from history.
+ *
+ * `compareAnswers` is the diff behind `sweny runs diff` and the "since last
+ * run" line. Identity rules (what counts as "the same finding") are explicit
+ * and tested; see {@link itemIdentity}.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { redact } from "../journal.js";
+import { writeFileNoFollow } from "../safe-file.js";
+import { RUN_HISTORY_DIR, RUN_ID_RE, listRuns } from "./run-history.js";
+export const RUN_ANSWERS_SCHEMA_VERSION = 1;
+/** Strings longer than this are cut (with an ellipsis) before they are stored. */
+export const ANSWER_STRING_MAX = 2000;
+const ANSWERS_READ_MAX_BYTES = 4 * 1024 * 1024;
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+// ── Build, write, read ──────────────────────────────────────────
+const has = (o, k) => Object.hasOwn(o, k);
+const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+/**
+ * Keep only what the schema declares, deep: `findings[].title` keeps `title` and nothing else. An
+ * object with no declared properties is dropped (nothing in it was declared); scalars are kept.
+ * Undefined means "drop".
+ */
+function pick(value, schema) {
+    const sch = isObj(schema) ? schema : undefined;
+    if (Array.isArray(value)) {
+        const items = sch && isObj(sch.items) ? sch.items : undefined;
+        return value.map((v) => pick(v, items)).filter((v) => v !== undefined);
+    }
+    if (isObj(value)) {
+        const props = sch && isObj(sch.properties) ? sch.properties : undefined;
+        if (!props)
+            return undefined;
+        return Object.fromEntries(Object.keys(props)
+            .filter((k) => has(value, k))
+            .map((k) => [k, pick(value[k], props[k])])
+            .filter(([, v]) => v !== undefined));
+    }
+    return value;
+}
+/** Secrets in keys too (`redact` scrubs values and keeps keys). */
+function redactKeys(value, secrets) {
+    if (Array.isArray(value))
+        return value.map((v) => redactKeys(v, secrets));
+    if (!isObj(value))
+        return value;
+    const seen = new Map();
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => {
+        let name = redact(k, secrets).value;
+        const n = (seen.get(name) ?? 0) + 1;
+        seen.set(name, n);
+        if (n > 1)
+            name = `${name}#${n}`;
+        return [name, redactKeys(v, secrets)];
+    }));
+}
+/** [display value, digest tree]: strings over the cap are cut, and their full-text sha256 goes in the tree. */
+function clipTree(value) {
+    if (typeof value === "string") {
+        return value.length > ANSWER_STRING_MAX
+            ? [value.slice(0, ANSWER_STRING_MAX) + "…", sha(value)]
+            : [value, undefined];
+    }
+    if (Array.isArray(value)) {
+        const pairs = value.map(clipTree);
+        return [pairs.map((p) => p[0]), pairs.some((p) => p[1] !== undefined) ? pairs.map((p) => p[1] ?? null) : undefined];
+    }
+    if (isObj(value)) {
+        const pairs = Object.entries(value).map(([k, v]) => [k, clipTree(v)]);
+        const digs = pairs.filter(([, p]) => p[1] !== undefined).map(([k, p]) => [k, p[1]]);
+        return [
+            Object.fromEntries(pairs.map(([k, p]) => [k, p[0]])),
+            digs.length > 0 ? Object.fromEntries(digs) : undefined,
+        ];
+    }
+    return [value, undefined];
+}
+/**
+ * Declared fields of each successful node, deep, redacted (values and keys). A failed or skipped
+ * node records nothing, so the diff never reads a failure as "everything resolved".
+ */
+export function buildRunAnswers(i) {
+    const secrets = i.secrets ?? [];
+    const nodes = [];
+    const digests = [];
+    for (const [id, r] of i.results) {
+        if (r.status !== "success")
+            continue;
+        const data = r.data ?? {};
+        const schema = has(i.workflow.nodes, id) ? i.workflow.nodes[id]?.output : undefined;
+        const props = isObj(schema) ? schema.properties : undefined;
+        let fields;
+        if (isObj(props) && Object.keys(props).length > 0) {
+            fields = pick(data, schema);
+        }
+        else if (typeof data.summary === "string" && data.summary.trim() !== "") {
+            fields = { summary: data.summary };
+        }
+        if (!isObj(fields) || Object.keys(fields).length === 0)
+            continue;
+        const clean = redactKeys(redact(fields, secrets).value, secrets);
+        const [shown, digs] = clipTree(clean);
+        nodes.push([id, shown]);
+        if (digs !== undefined)
+            digests.push([id, digs]);
+    }
+    return {
+        schema_version: RUN_ANSWERS_SCHEMA_VERSION,
+        run_id: i.runId,
+        workflow_id: i.workflow.id,
+        nodes: Object.fromEntries(nodes),
+        ...(digests.length > 0 ? { digests: Object.fromEntries(digests) } : {}),
+    };
+}
+/** Relative path: `.sweny/runs/<id>/answers.json`. */
+export function answersRelPath(runId) {
+    return path.posix.join(...RUN_HISTORY_DIR.split(path.sep), runId, "answers.json");
+}
+/** Write answers.json (mode 0600; the run dir ignores itself in git). Returns the relative path, or null. Never throws. */
+export function writeRunAnswers(answers, cwd = process.cwd()) {
+    try {
+        if (!RUN_ID_RE.test(answers.run_id))
+            return null;
+        const rel = answersRelPath(answers.run_id);
+        const file = path.join(cwd, rel);
+        writeFileNoFollow(path.join(path.dirname(file), ".gitignore"), "*\n", { root: cwd, mode: 0o644 });
+        writeFileNoFollow(file, JSON.stringify(answers, null, 2) + "\n", { root: cwd, mode: 0o600 });
+        return rel;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read a run's answers. Null when the id is not a generated run id (checked before any path is
+ * built), the file is missing, oversized, reached through a link, corrupt, an unknown schema
+ * version, or carries a different run id than the one asked for.
+ */
+export function readRunAnswers(runId, cwd = process.cwd()) {
+    try {
+        if (typeof runId !== "string" || !RUN_ID_RE.test(runId))
+            return null;
+        const rel = answersRelPath(runId);
+        const file = path.join(cwd, rel);
+        // No link on the path: the real path must be exactly where the id says it is.
+        if (fs.realpathSync(file) !== path.join(fs.realpathSync(cwd), rel))
+            return null;
+        const st = fs.lstatSync(file);
+        if (!st.isFile() || st.size > ANSWERS_READ_MAX_BYTES)
+            return null;
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (!isObj(parsed) ||
+            parsed.schema_version !== RUN_ANSWERS_SCHEMA_VERSION ||
+            parsed.run_id !== runId ||
+            typeof parsed.workflow_id !== "string" ||
+            !isObj(parsed.nodes) ||
+            !Object.values(parsed.nodes).every(isObj) ||
+            (parsed.digests !== undefined && (!isObj(parsed.digests) || !Object.values(parsed.digests).every(isObj)))) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Identity ────────────────────────────────────────────────────
+/** Fields that name an item, in priority order. */
+export const IDENTITY_KEYS = ["id", "key", "fingerprint", "title", "name"];
+const normalize = (s) => s.trim().toLowerCase().replace(/\s+/g, " ");
+function canonical(value) {
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (isObj(v)) {
+            return Object.fromEntries(Object.keys(v)
+                .sort()
+                .filter((k) => v[k] !== undefined)
+                .map((k) => [k, walk(v[k])]));
+        }
+        return v;
+    };
+    return JSON.stringify(walk(value));
+}
+const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+/** The raw (un-normalized) identity value of an object item, or undefined. */
+function identityRaw(item) {
+    for (const k of IDENTITY_KEYS) {
+        const v = has(item, k) ? item[k] : undefined;
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+        if (typeof v === "number" && Number.isFinite(v))
+            return String(v);
+    }
+    return undefined;
+}
+/**
+ * "Is this the same finding as that one?" The rule, in order:
+ *  1. An object item is identified by the first of `id`, `key`, `fingerprint`,
+ *     `title`, `name` that holds a non-empty string or a number, normalized
+ *     (trimmed, lowercased, whitespace collapsed).
+ *  2. An object with none of those is identified by its whole content (a
+ *     short hash of its canonical JSON): any edit reads as resolved + added.
+ *  3. A plain string, number or boolean item is identified by its normalized value.
+ * Two items of one list with the same identity pair up in order.
+ */
+export function itemIdentity(item) {
+    if (isObj(item)) {
+        const raw = identityRaw(item);
+        if (raw !== undefined)
+            return normalize(raw);
+        return "content:" + crypto.createHash("sha256").update(canonical(item)).digest("hex").slice(0, 12);
+    }
+    return normalize(String(item));
+}
+function itemLabel(item) {
+    if (!isObj(item))
+        return String(item);
+    const raw = identityRaw(item);
+    if (raw !== undefined)
+        return raw;
+    for (const v of Object.values(item))
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    return canonical(item);
+}
+/** A list of objects, or a list of scalars. Mixed lists are compared as one opaque value. */
+function isCollection(v) {
+    return Array.isArray(v) && (v.every(isObj) || v.every(isScalar));
+}
+/** The digest subtree for `key` (an object key or array index), if any. */
+function sub(d, key) {
+    if (Array.isArray(d) && typeof key === "number")
+        return d[key] ?? undefined;
+    if (isObj(d) && typeof key === "string" && has(d, key))
+        return d[key];
+    return undefined;
+}
+/** Equal stored text AND equal digests: equal full values. */
+const sameHeld = (a, b) => canonical(a.v) === canonical(b.v) && canonical(a.d ?? null) === canonical(b.d ?? null);
+function indexByIdentity(items) {
+    const m = new Map();
+    for (const it of items) {
+        const id = itemIdentity(it.v);
+        const list = m.get(id);
+        if (list)
+            list.push(it);
+        else
+            m.set(id, [it]);
+    }
+    return m;
+}
+function fieldChanges(before, after) {
+    if (!isObj(before.v) || !isObj(after.v))
+        return [{ field: "value", before: before.v, after: after.v }];
+    const b = before.v;
+    const a = after.v;
+    const out = [];
+    for (const k of [...new Set([...Object.keys(b), ...Object.keys(a)])].sort()) {
+        const had = has(b, k) && b[k] !== undefined;
+        const hasNow = has(a, k) && a[k] !== undefined;
+        if (had && hasNow) {
+            if (!sameHeld({ v: b[k], d: sub(before.d, k) }, { v: a[k], d: sub(after.d, k) })) {
+                out.push({ field: k, before: b[k], after: a[k] });
+            }
+        }
+        else if (had)
+            out.push({ field: k, before: b[k] });
+        else if (hasNow)
+            out.push({ field: k, after: a[k] });
+    }
+    return out;
+}
+const heldItems = (h) => h && Array.isArray(h.v) ? h.v.map((v, i) => ({ v, d: sub(h.d, i) })) : [];
+function compareCollection(node, field, a, b) {
+    const ai = indexByIdentity(heldItems(a));
+    const bi = indexByIdentity(heldItems(b));
+    const e = { node, field, kind: "collection", added: [], resolved: [], changed: [], unchanged: 0 };
+    for (const [id, bItems] of bi) {
+        const aItems = ai.get(id) ?? [];
+        bItems.forEach((item, n) => {
+            if (n >= aItems.length) {
+                e.added.push({ id, label: itemLabel(item.v), value: item.v });
+            }
+            else if (sameHeld(aItems[n], item)) {
+                e.unchanged++;
+            }
+            else {
+                e.changed.push({ id, label: itemLabel(item.v), fields: fieldChanges(aItems[n], item) });
+            }
+        });
+    }
+    for (const [id, aItems] of ai) {
+        const bCount = bi.get(id)?.length ?? 0;
+        aItems.slice(bCount).forEach((item) => e.resolved.push({ id, label: itemLabel(item.v), value: item.v }));
+    }
+    return e;
+}
+function compareField(node, field, a, b) {
+    if ((a === undefined || isCollection(a.v)) &&
+        (b === undefined || isCollection(b.v)) &&
+        (a !== undefined || b !== undefined)) {
+        const e = compareCollection(node, field, a, b);
+        return e.added.length + e.resolved.length + e.changed.length + e.unchanged === 0 ? null : e;
+    }
+    if (!a)
+        return { node, field, kind: "value", status: "added", after: b?.v };
+    if (!b)
+        return { node, field, kind: "value", status: "resolved", before: a.v };
+    if (sameHeld(a, b))
+        return { node, field, kind: "value", status: "unchanged" };
+    return { node, field, kind: "value", status: "changed", before: a.v, after: b.v };
+}
+/** node -> field -> value + digests. Maps, so a node or field named `constructor` or `__proto__` is just a name. */
+function heldByNode(r) {
+    const out = new Map();
+    for (const [node, fields] of Object.entries(r.nodes)) {
+        const digs = r.digests && has(r.digests, node) && isObj(r.digests[node]) ? r.digests[node] : undefined;
+        out.set(node, new Map(Object.entries(fields).map(([f, v]) => [f, { v, d: digs ? sub(digs, f) : undefined }])));
+    }
+    return out;
+}
+/**
+ * Compare an older run's answers (a) with a newer one's (b), node by node and
+ * field by field. A list field (all objects, or all scalars) is diffed item by
+ * item using {@link itemIdentity}; any other field is one value. Cut strings
+ * compare by the digest of their full text.
+ */
+export function compareAnswers(a, b) {
+    if (!a || !b) {
+        const missing = [];
+        if (!a)
+            missing.push("a");
+        if (!b)
+            missing.push("b");
+        return { available: false, reason: "missing_answers", missing };
+    }
+    if (a.workflow_id !== b.workflow_id)
+        return { available: false, reason: "different_workflows" };
+    const am = heldByNode(a);
+    const bm = heldByNode(b);
+    const counts = { added: 0, resolved: 0, changed: 0, unchanged: 0 };
+    const entries = [];
+    const not_compared = [];
+    for (const node of new Set([...bm.keys(), ...am.keys()])) {
+        const an = am.get(node);
+        const bn = bm.get(node);
+        if (!an || !bn) {
+            not_compared.push({ node, only_in: an ? "a" : "b" });
+            continue;
+        }
+        for (const field of new Set([...bn.keys(), ...an.keys()])) {
+            const e = compareField(node, field, an.get(field), bn.get(field));
+            if (!e)
+                continue;
+            entries.push(e);
+            if (e.kind === "collection") {
+                counts.added += e.added.length;
+                counts.resolved += e.resolved.length;
+                counts.changed += e.changed.length;
+                counts.unchanged += e.unchanged;
+            }
+            else {
+                counts[e.status]++;
+            }
+        }
+    }
+    return { available: true, counts, entries, not_compared };
+}
+/**
+ * Compare a recorded run with the run of the same workflow just before it. `workflowId` comes from
+ * the caller's loaded workflow; history only picks WHICH earlier run, never what is printed.
+ * Null when there is no earlier run, either run has no answers, or anything fails.
+ */
+export function sinceLastRun(runId, workflowId, cwd = process.cwd()) {
+    try {
+        if (!RUN_ID_RE.test(runId))
+            return null;
+        const previous = listRuns(cwd).find(
+        // newest first
+        (r) => r.workflow_id === workflowId && r.run_id !== runId && r.run_id < runId);
+        if (!previous)
+            return null;
+        const cmp = compareAnswers(readRunAnswers(previous.run_id, cwd), readRunAnswers(runId, cwd));
+        if (!cmp.available)
+            return null;
+        return {
+            workflow_id: workflowId,
+            previous_run_id: previous.run_id,
+            counts: cmp.counts,
+            not_compared: cmp.not_compared.length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Save this run's answers, then compare with the previous run. Never throws. */
+export function recordRunAnswers(i, cwd = process.cwd()) {
+    try {
+        if (!writeRunAnswers(buildRunAnswers(i), cwd))
+            return null;
+        return sinceLastRun(i.runId, i.workflow.id, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+// The public line is built from a fixed template, a validated id and integers: nothing else.
+/** A workflow id that is safe in a shell word and a markdown code span. Anything else drops the flag. */
+const SAFE_WORKFLOW_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const count = (n) => (typeof n === "number" && Number.isSafeInteger(n) && n >= 0 ? n : 0);
+const diffCommand = (s) => typeof s.workflow_id === "string" && SAFE_WORKFLOW_ID.test(s.workflow_id)
+    ? `sweny runs diff --workflow ${s.workflow_id}`
+    : "sweny runs diff";
+/** `2 added, 1 resolved, 1 changed` from the nonzero counts (`no changes` when none), then the not-compared nodes. */
+function countsText(s) {
+    const c = s.counts ?? {};
+    const parts = [
+        count(c.added) ? `${count(c.added)} added` : "",
+        count(c.resolved) ? `${count(c.resolved)} resolved` : "",
+        count(c.changed) ? `${count(c.changed)} changed` : "",
+    ].filter(Boolean);
+    const text = parts.length > 0 ? parts.join(", ") : "no changes";
+    const skipped = count(s.not_compared);
+    return skipped ? `${text}, ${skipped} not compared: failed or no output` : text;
+}
+/** Plain text, one line: for the terminal and CI logs. */
+export function formatSinceLast(s) {
+    return `since last run: ${countsText(s)} (${diffCommand(s)})`;
+}
+/** Markdown, one line: for the step summary and the PR comment. */
+export function formatSinceLastMarkdown(s) {
+    return `Since last run: ${countsText(s)}. Compare: \`${diffCommand(s)}\``;
+}

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

@@ -4,7 +4,8 @@
  *
  * 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.
+ * inputs/outputs, error text, or environment values. What a run answered is
+ * kept apart, in `<run-id>/answers.json` (run-answers.ts).
  *
  * `schema_version` is the compatibility contract: a future resume journal
  * builds on this format, so readers skip records with a version they do not
@@ -60,6 +61,8 @@ export interface RunRecord {
 }
 /** sha256 (hex) of the workflow as canonical JSON: keys sorted, undefined dropped. */
 export declare function hashWorkflow(workflow: Workflow): string;
+/** The shape `newRunId` generates. Anything else is not a run id. */
+export declare const RUN_ID_RE: RegExp;
 /** 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 {
@@ -88,7 +91,12 @@ export declare function pruneRuns(cwd?: string, keep?: number): number;
 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. */
+/**
+ * All readable records, newest first. Corrupt files and unknown schema versions
+ * are skipped. History is agent-writable, so a record is trusted only when its
+ * run_id has the generated shape, matches its filename, and is not repeated:
+ * a planted copy of another run's id is dropped, not merged.
+ */
 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

@@ -4,7 +4,8 @@
  *
  * 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.
+ * inputs/outputs, error text, or environment values. What a run answered is
+ * kept apart, in `<run-id>/answers.json` (run-answers.ts).
  *
  * `schema_version` is the compatibility contract: a future resume journal
  * builds on this format, so readers skip records with a version they do not
@@ -40,7 +41,8 @@ export function hashWorkflow(workflow) {
         .update(JSON.stringify(canonicalize(workflow)))
         .digest("hex");
 }
-const RUN_ID_RE = /^\d{8}-\d{6}-[0-9a-f]{6}$/;
+/** The shape `newRunId` generates. Anything else is not a run id. */
+export 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);
@@ -195,7 +197,12 @@ function isRecord(v) {
         !!r.totals &&
         typeof r.totals === "object");
 }
-/** All readable records, newest first. Corrupt files and unknown schema versions are skipped. */
+/**
+ * All readable records, newest first. Corrupt files and unknown schema versions
+ * are skipped. History is agent-writable, so a record is trusted only when its
+ * run_id has the generated shape, matches its filename, and is not repeated:
+ * a planted copy of another run's id is dropped, not merged.
+ */
 export function listRuns(cwd = process.cwd()) {
     const dir = path.join(cwd, RUN_HISTORY_DIR);
     let files;
@@ -209,14 +216,19 @@ export function listRuns(cwd = process.cwd()) {
     for (const f of files) {
         try {
             const parsed = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
-            if (isRecord(parsed))
+            if (isRecord(parsed) && RUN_ID_RE.test(parsed.run_id) && f === `${parsed.run_id}.json`)
                 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));
+    const seen = new Map();
+    for (const r of out)
+        seen.set(r.run_id, (seen.get(r.run_id) ?? 0) + 1);
+    return out
+        .filter((r) => seen.get(r.run_id) === 1)
+        .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) {

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

@@ -106,13 +106,13 @@ export declare function renderReceiptLine(s: RunSummary, color: boolean): string
 /** Per-node Mermaid status from run results. */
 export declare function nodeStates(results: Map<string, NodeResult>): Record<string, NodeStatus>;
 /** Markdown for `$GITHUB_STEP_SUMMARY`: receipt + Mermaid DAG in the brand classDefs. */
-export declare function formatStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace): string;
+export declare function formatStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace, sinceLast?: string | null): string;
 /**
  * Append the step summary to the file named by GITHUB_STEP_SUMMARY.
  * Runner-agnostic: does nothing when the variable is unset or empty.
  * Never throws; returns true only when something was written.
  */
-export declare function writeStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace, env?: NodeJS.ProcessEnv): boolean;
+export declare function writeStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace, env?: NodeJS.ProcessEnv, sinceLast?: string | null): boolean;
 export interface RunLogger extends Logger {
     /** Write any warnings held back while a node line was live. */
     flush(): void;

package/dist/cli/run-output.js

@@ -211,13 +211,15 @@ export function nodeStates(results) {
     return state;
 }
 /** Markdown for `$GITHUB_STEP_SUMMARY`: receipt + Mermaid DAG in the brand classDefs. */
-export function formatStepSummary(workflow, results, summary, trace) {
+export function formatStepSummary(workflow, results, summary, trace, sinceLast) {
     const state = nodeStates(results);
     return [
         `## ${summary.ok ? "✅" : "❌"} ${workflow.name}`,
         "",
         `\`${formatReceipt(summary)}\``,
         "",
+        // The "since last run" line (run-answers.ts formatSinceLastMarkdown): counts only, never node outputs.
+        ...(sinceLast ? [sinceLast, ""] : []),
         toMermaidBlock(workflow, { state, trace }),
         "",
         "",
@@ -228,14 +230,14 @@ export function formatStepSummary(workflow, results, summary, trace) {
  * Runner-agnostic: does nothing when the variable is unset or empty.
  * Never throws; returns true only when something was written.
  */
-export function writeStepSummary(workflow, results, summary, trace, env = process.env) {
+export function writeStepSummary(workflow, results, summary, trace, env = process.env, sinceLast) {
     // The operator's value only: never one a workspace `.env` introduced.
     const file = trustedEnvValue(env, "GITHUB_STEP_SUMMARY");
     if (!file)
         return false;
     try {
         // Never through a link, in case the path sits in the agent-writable workspace.
-        writeFileNoFollow(file, formatStepSummary(workflow, results, summary, trace), {
+        writeFileNoFollow(file, formatStepSummary(workflow, results, summary, trace, sinceLast), {
             ...workspaceRoot(file),
             append: true,
             mkdirs: false,

package/dist/cli/runs.d.ts

@@ -1,12 +1,29 @@
 /**
  * `sweny runs` and `sweny runs diff`: read-only views over `.sweny/runs/`.
- * Metadata only. Color only when `color` is true (TTY).
+ * `runs` lists metadata. `runs diff` compares the metadata of two runs and,
+ * first, what changed in their answers (run-answers.ts). Color only when
+ * `color` is true (TTY and no NO_COLOR); the glyph set follows `unicode`.
+ * The diff always ends on one plain line with the answer counts.
  */
 import type { Command } from "commander";
 import { type RunRecord } from "./run-history.js";
+import { type AnswersComparison } from "./run-answers.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;
+/**
+ * A copy of a history record that is safe to print. `.sweny/runs/` is writable by an agent, so every
+ * string read from a record goes through {@link sanitizeTerminal} (control sequences stripped, length
+ * capped) and every number is coerced to a finite number. Only for display: matching and `--json`
+ * use the record as read.
+ */
+export declare function printableRun(r: RunRecord): RunRecord;
+export declare function formatRunsTable(records: RunRecord[], color: boolean, nowMs?: number, unicode?: boolean): string;
+export interface RunDiffOptions {
+    /** Answer comparison for the pair; when set the diff leads with it and ends on its summary line. */
+    answers?: AnswersComparison;
+    /** Unicode glyphs (default) or the ASCII set. */
+    unicode?: boolean;
+}
+export declare function formatRunDiff(rawA: RunRecord, rawB: RunRecord, color: boolean, opts?: RunDiffOptions): 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;
@@ -14,4 +31,26 @@ export declare function pickRunsForDiff(runs: RunRecord[], refs: string[], workf
 } | {
     error: string;
 };
+type OutStream = {
+    isTTY?: boolean;
+    write(chunk: string): unknown;
+};
+export interface RunsDiffIo {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdout: OutStream;
+    stderr: OutStream;
+}
+/**
+ * Body of `sweny runs diff`. Returns the exit code (0 diffed, 1 nothing to diff).
+ *
+ * `--json` prints `{ schema_version: 1, a: RunRecord, b: RunRecord, answers }` and never ANSI.
+ * `answers` is `{ available: true, counts, entries, not_compared }` or
+ * `{ available: false, reason: "different_workflows" | "missing_answers", missing? }`.
+ */
+export declare function runRunsDiff(refs: string[], opts: {
+    workflow?: string;
+    json?: boolean;
+}, io: RunsDiffIo): number;
 export declare function registerRunsCommand(program: Command): Command;
+export {};