@sweny-ai/core 0.1.159 → 0.1.161

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

@@ -0,0 +1,41 @@
+/**
+ * The answer at the end of `sweny workflow run`: the terminal node's result
+ * (or the failed node's error), rendered for a human.
+ *
+ * Unlike run-history and the receipt, this DOES read node output. It is
+ * local-only: printed to the terminal and saved to
+ * `.sweny/runs/<run-id>/output.md`. Nothing here is sent to the cloud.
+ */
+import type { JSONSchema, NodeResult, Workflow } from "../types.js";
+/** Lines of the answer printed to the terminal before the rest is left in output.md. */
+export declare const FINAL_OUTPUT_MAX_LINES = 60;
+export interface FinalOutput {
+    kind: "result" | "error";
+    /** Node id the text came from. */
+    node: string;
+    /** Rendered lines, uncapped. */
+    lines: string[];
+}
+/** Render a node's declared output fields as a compact `key: value` block. Empty when nothing declared is present. */
+export declare function renderSchemaOutput(data: Record<string, unknown>, schema: JSONSchema): string[];
+/**
+ * Pick what the user should see: the last-run terminal node's result on
+ * success, the first failed node's error on failure. Null when there is
+ * nothing to show (no schema fields and no summary text).
+ */
+export declare function resolveFinalOutput(workflow: Workflow, results: Map<string, NodeResult>): FinalOutput | null;
+/**
+ * Terminal text: the first `maxLines` lines, then
+ * `... (N more lines, see .sweny/runs/<id>/output.md)`. When no file was
+ * saved the pointer is dropped, never invented.
+ */
+export declare function formatFinalOutput(out: FinalOutput, opts?: {
+    maxLines?: number;
+    outputPath?: string | null;
+}): string;
+/** Markdown saved to output.md: the full, uncapped answer. */
+export declare function formatFinalMarkdown(workflow: Workflow, out: FinalOutput): string;
+/** Relative path shown to the user: `.sweny/runs/<id>/output.md`. */
+export declare function outputRelPath(runId: string): string;
+/** Write output.md. Local only. Returns the relative path, or null on failure. Never throws. */
+export declare function writeFinalOutput(runId: string, markdown: string, cwd?: string): string | null;

package/dist/cli/final-output.js

@@ -0,0 +1,155 @@
+/**
+ * The answer at the end of `sweny workflow run`: the terminal node's result
+ * (or the failed node's error), rendered for a human.
+ *
+ * Unlike run-history and the receipt, this DOES read node output. It is
+ * local-only: printed to the terminal and saved to
+ * `.sweny/runs/<run-id>/output.md`. Nothing here is sent to the cloud.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { RUN_HISTORY_DIR } from "./run-history.js";
+/** Lines of the answer printed to the terminal before the rest is left in output.md. */
+export const FINAL_OUTPUT_MAX_LINES = 60;
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function isEmpty(v) {
+    return (v === undefined ||
+        v === null ||
+        (typeof v === "string" && v.trim() === "") ||
+        (Array.isArray(v) && v.length === 0) ||
+        (isObj(v) && Object.keys(v).length === 0));
+}
+function scalar(v) {
+    return typeof v === "string" ? v : JSON.stringify(v);
+}
+function indentLines(lines, pad) {
+    return lines.map((l) => (l === "" ? l : pad + l));
+}
+/** One value as lines under a label: `key: value`, or `key:` plus an indented block. */
+function renderField(label, value, schema) {
+    if (Array.isArray(value)) {
+        const itemSchema = isObj(schema?.items) ? schema.items : undefined;
+        const out = [`${label}:`];
+        for (const item of value)
+            out.push(...renderListItem(item, itemSchema));
+        return out;
+    }
+    if (isObj(value)) {
+        return [`${label}:`, ...indentLines(renderObject(value, schema), "  ")];
+    }
+    const text = scalar(value);
+    if (!text.includes("\n"))
+        return [`${label}: ${text}`];
+    return [`${label}:`, ...indentLines(text.split("\n"), "  ")];
+}
+function renderListItem(item, schema) {
+    if (isObj(item)) {
+        const inner = renderObject(item, schema);
+        if (inner.length === 0)
+            return [];
+        return [`- ${inner[0]}`, ...indentLines(inner.slice(1), "  ")];
+    }
+    if (Array.isArray(item)) {
+        return [`- ${item.map(scalar).join(", ")}`];
+    }
+    const text = scalar(item);
+    const [first, ...rest] = text.split("\n");
+    return [`- ${first}`, ...indentLines(rest, "  ")];
+}
+/** Declared fields first (schema order), then none of the extras: the schema is the contract. */
+function renderObject(data, schema) {
+    const props = isObj(schema?.properties) ? schema.properties : undefined;
+    const keys = props ? Object.keys(props) : Object.keys(data);
+    const out = [];
+    for (const key of keys) {
+        const value = data[key];
+        if (isEmpty(value))
+            continue;
+        const propSchema = props && isObj(props[key]) ? props[key] : undefined;
+        const title = typeof propSchema?.title === "string" && propSchema.title.trim() ? propSchema.title.trim() : key;
+        out.push(...renderField(title, value, propSchema));
+    }
+    return out;
+}
+/** Render a node's declared output fields as a compact `key: value` block. Empty when nothing declared is present. */
+export function renderSchemaOutput(data, schema) {
+    const props = schema.properties;
+    if (!isObj(props) || Object.keys(props).length === 0)
+        return [];
+    return renderObject(data, schema);
+}
+function trimBlock(text) {
+    const lines = text.replace(/\r\n/g, "\n").trim().split("\n");
+    return lines.map((l) => l.replace(/\s+$/, ""));
+}
+/**
+ * Pick what the user should see: the last-run terminal node's result on
+ * success, the first failed node's error on failure. Null when there is
+ * nothing to show (no schema fields and no summary text).
+ */
+export function resolveFinalOutput(workflow, results) {
+    for (const [id, r] of results) {
+        if (r.status !== "failed")
+            continue;
+        const err = r.data?.error;
+        const text = typeof err === "string" && err.trim() !== "" ? err : "node failed";
+        return { kind: "error", node: id, lines: trimBlock(text) };
+    }
+    const hasOutgoing = new Set(workflow.edges.map((e) => e.from));
+    const succeeded = [...results].filter(([, r]) => r.status === "success");
+    const terminal = succeeded.filter(([id]) => !hasOutgoing.has(id));
+    // Walk back from the end: the last node that actually yields something wins.
+    const candidates = [...(terminal.length > 0 ? terminal : succeeded)].reverse();
+    for (const [id, r] of candidates) {
+        const schema = workflow.nodes[id]?.output;
+        let lines = [];
+        if (schema)
+            lines = renderSchemaOutput(r.data ?? {}, schema);
+        if (lines.length === 0) {
+            const summary = r.data?.summary;
+            if (typeof summary === "string" && summary.trim() !== "")
+                lines = trimBlock(summary);
+        }
+        if (lines.length > 0)
+            return { kind: "result", node: id, lines };
+    }
+    return null;
+}
+/**
+ * Terminal text: the first `maxLines` lines, then
+ * `... (N more lines, see .sweny/runs/<id>/output.md)`. When no file was
+ * saved the pointer is dropped, never invented.
+ */
+export function formatFinalOutput(out, opts = {}) {
+    const max = opts.maxLines ?? FINAL_OUTPUT_MAX_LINES;
+    const shown = out.lines.slice(0, max);
+    const hidden = out.lines.length - shown.length;
+    if (hidden > 0) {
+        const noun = hidden === 1 ? "line" : "lines";
+        shown.push(opts.outputPath ? `... (${hidden} more ${noun}, see ${opts.outputPath})` : `... (${hidden} more ${noun})`);
+    }
+    return shown.map((l) => (l === "" ? "" : `  ${l}`)).join("\n");
+}
+/** Markdown saved to output.md: the full, uncapped answer. */
+export function formatFinalMarkdown(workflow, out) {
+    const nodeName = workflow.nodes[out.node]?.name ?? out.node;
+    const head = out.kind === "error" ? `# ${workflow.name}: ${nodeName} failed` : `# ${workflow.name}`;
+    return `${head}\n\n${out.lines.join("\n")}\n`;
+}
+/** Relative path shown to the user: `.sweny/runs/<id>/output.md`. */
+export function outputRelPath(runId) {
+    return path.posix.join(...RUN_HISTORY_DIR.split(path.sep), runId, "output.md");
+}
+/** Write output.md. Local only. Returns the relative path, or null on failure. Never throws. */
+export function writeFinalOutput(runId, markdown, cwd = process.cwd()) {
+    try {
+        const rel = outputRelPath(runId);
+        const file = path.join(cwd, rel);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, markdown);
+        return rel;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/main.d.ts

@@ -17,3 +17,6 @@ export declare function workflowExportAction(name: string): void;
 export declare function workflowValidateAction(file: string, options: {
     json?: boolean;
 }): void;
+export declare function workflowUpgradeAction(file: string, options: {
+    dryRun?: boolean;
+}): void;

package/dist/cli/main.js

@@ -19,6 +19,7 @@ import { configuredSkills, configuredSkillsWithDiagnostics } from "../skills/cus
 import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "../mcp.js";
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
+import { upgradeWorkflowFile } from "./workflow-upgrade.js";
 import { validateRuntimeInput } from "../inputs.js";
 import { mergeDryRunIntoInput, parseInputFlag, parseRunBudgetFlags, parseSpendFlags } from "./workflow-input.js";
 import { stringify as stringifyYaml } from "yaml";
@@ -30,6 +31,7 @@ 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 { formatFinalMarkdown, formatFinalOutput, resolveFinalOutput, writeFinalOutput } from "./final-output.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";
@@ -724,6 +726,8 @@ export function loadWorkflowFile(filePath, knownSkills) {
     if (!result.ok) {
         throw new Error(`Invalid workflow file:\n${result.errors.map((e) => `  ${e.message}`).join("\n")}`);
     }
+    for (const w of result.warnings ?? [])
+        console.error(chalk.yellow(`  \u26A0 ${w}`));
     return result.workflow;
 }
 export async function workflowRunAction(file, options) {
@@ -1049,6 +1053,19 @@ export async function workflowRunAction(file, options) {
         runLogger.flush();
         const receipt = summarizeRun(results, wfDurationMs);
         writeStepSummary(workflow, results, receipt, trace);
+        // The answer, above the receipt: the terminal node's result, or the failed node's error.
+        // Also saved to .sweny/runs/<id>/output.md (local only; --no-history skips the file).
+        const finalOutput = resolveFinalOutput(workflow, results);
+        if (finalOutput) {
+            const savedTo = historyDisabled(options.history, fileConfig["history"])
+                ? null
+                : writeFinalOutput(runId, formatFinalMarkdown(workflow, finalOutput));
+            const block = formatFinalOutput(finalOutput, { outputPath: savedTo });
+            if (wfHasFailed)
+                console.error(`${block}\n`);
+            else
+                console.log(`${block}\n`);
+        }
         if (wfHasFailed) {
             console.error(`  ${renderReceiptLine(receipt, isTTY)}\n`);
             process.exit(1);
@@ -1108,7 +1125,10 @@ export function workflowValidateAction(file, options) {
     const result = loadAndValidateWorkflow(file);
     // Missing skill env is a warning here, not a failure: `run` is where it blocks.
     const warnings = result.ok
-        ? skillEnvWarnings(result.workflow, process.env, builtinSkills.concat(configuredSkills(process.env, process.cwd())))
+        ? [
+            ...(result.warnings ?? []),
+            ...skillEnvWarnings(result.workflow, process.env, builtinSkills.concat(configuredSkills(process.env, process.cwd()))),
+        ]
         : [];
     if (options.json) {
         const errs = result.ok ? [] : result.errors;
@@ -1135,6 +1155,29 @@ workflowCmd
     .description("Validate a workflow YAML or JSON file")
     .option("--json", "Output result as JSON")
     .action(workflowValidateAction);
+export function workflowUpgradeAction(file, options) {
+    const result = upgradeWorkflowFile(file, { dryRun: options.dryRun });
+    if (result.status === "error") {
+        console.error(chalk.red(`  \u2717 ${result.message}`));
+        process.exit(1);
+        return;
+    }
+    if (result.status === "current") {
+        console.log(chalk.green(`  \u2713 ${file} is already at spec_version "${result.version}"`));
+        return;
+    }
+    const verb = result.status === "dry-run" ? "Would upgrade" : "Upgraded";
+    console.log(chalk.green(`  \u2713 ${verb} ${file}: spec_version "${result.from}" -> "${result.to}"`));
+    for (const step of result.steps)
+        console.log(chalk.dim(`    - ${step}`));
+    if (result.status === "dry-run")
+        console.log(chalk.dim("    (dry run, file not changed)"));
+}
+workflowCmd
+    .command("upgrade <file>")
+    .description("Rewrite a workflow file at the current spec version (comments are kept where possible)")
+    .option("--dry-run", "Show what would change without writing the file")
+    .action(workflowUpgradeAction);
 const workflowRunCmd = workflowCmd
     .command("run [file]")
     .description(WORKFLOW_RUN_DESCRIPTION)
@@ -1142,7 +1185,7 @@ 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)");
+workflowRunCmd.option("--no-history", "Do not record this run or save its output.md in .sweny/runs/ (or set `history: off` in .sweny.yml)");
 registerRunsCommand(program);
 workflowCmd
     .command("diagram <file>")

package/dist/cli/run-history.js

@@ -153,8 +153,11 @@ export function pruneRuns(cwd = process.cwd(), keep = RUN_HISTORY_KEEP) {
             .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)
+        for (const f of extra) {
             fs.rmSync(path.join(dir, f), { force: true });
+            // output.md lives beside the record in <run-id>/ (final-output.ts)
+            fs.rmSync(path.join(dir, f.slice(0, -5)), { recursive: true, force: true });
+        }
         return extra.length;
     }
     catch {

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

@@ -25,6 +25,12 @@ export interface RunSummary {
      * (`max_turns`, `egress allowlist`, `deny [write]`). Absent when none.
      */
     degraded?: string[];
+    /**
+     * What the run's opinions did, from facts the nodes reported: env scope and
+     * sandbox (Claude Code only) and safe-output counts. Absent when the run
+     * knows none of it.
+     */
+    policy?: RunPolicy;
     /** The spend budget a node crossed (#449). Absent when none was. */
     budget?: {
         node: string;
@@ -34,10 +40,29 @@ export interface RunSummary {
         spent: number;
     };
 }
+export interface RunPolicy {
+    /** Agent env narrowed to the allowlist. Absent when no node reported it. */
+    envScope?: boolean;
+    /** Sandbox facts. `started` is false when the mode asked for one but the host could not. */
+    sandbox?: {
+        mode: "off" | "auto" | "strict";
+        started: boolean;
+    };
+    /** Safe outputs staged (previewed) and applied (written), summed over nodes. */
+    outputs?: {
+        staged: number;
+        applied: number;
+    };
+}
 /** The short key of a `degraded` entry: the text before its first colon. */
 export declare function degradedKey(entry: string): string;
 /** Sum the per-node results into one run summary. */
 export declare function summarizeRun(results: Map<string, NodeResult>, durationMs: number, crashed?: boolean): RunSummary;
+/**
+ * `policy: env scoped, sandbox on, 1 output staged`. Only what the run knew:
+ * no segment for a fact no node reported. Undefined when there is nothing to say.
+ */
+export declare function formatPolicySegment(p: RunPolicy | undefined): string | undefined;
 export declare function formatReceiptDuration(ms: number): string;
 export declare function formatTokenCount(n: number): string;
 export declare function formatCost(usd: number): string;

package/dist/cli/run-output.js

@@ -25,6 +25,9 @@ export function summarizeRun(results, durationMs, crashed = false) {
     let harness;
     const degraded = new Set();
     let budget;
+    const policy = {};
+    let staged = 0;
+    let applied = 0;
     const isNum = (v) => typeof v === "number" && Number.isFinite(v);
     for (const [nodeId, r] of results) {
         if (r.budget && !budget)
@@ -32,6 +35,20 @@ export function summarizeRun(results, durationMs, crashed = false) {
         harness ??= r.harness?.id;
         for (const d of r.degraded ?? [])
             degraded.add(degradedKey(d));
+        if (r.policy) {
+            // Any node that ran unscoped or unsandboxed counts: the receipt must not overstate.
+            policy.envScope = policy.envScope === undefined ? r.policy.envScope : policy.envScope && r.policy.envScope;
+            const sb = { mode: r.policy.sandbox, started: r.policy.sandboxStarted };
+            // Keep the weakest node: the first one that did not run sandboxed.
+            if (!policy.sandbox || (policy.sandbox.started && !sb.started))
+                policy.sandbox = sb;
+        }
+        for (const o of r.outputs ?? []) {
+            if (o.status === "staged")
+                staged++;
+            else if (o.status === "applied")
+                applied++;
+        }
         if (r.status === "success")
             nodesOk++;
         else if (r.status === "skipped")
@@ -49,6 +66,8 @@ export function summarizeRun(results, durationMs, crashed = false) {
                 costUsd = (costUsd ?? 0) + u.costUsd;
         }
     }
+    if (staged > 0 || applied > 0)
+        policy.outputs = { staged, applied };
     return {
         ok: !failed,
         nodesOk,
@@ -60,9 +79,36 @@ export function summarizeRun(results, durationMs, crashed = false) {
         ...(costUsd !== undefined ? { costUsd } : {}),
         ...(harness !== undefined ? { harness } : {}),
         ...(degraded.size > 0 ? { degraded: [...degraded] } : {}),
+        ...(Object.keys(policy).length > 0 ? { policy } : {}),
         ...(budget ? { budget } : {}),
     };
 }
+/**
+ * `policy: env scoped, sandbox on, 1 output staged`. Only what the run knew:
+ * no segment for a fact no node reported. Undefined when there is nothing to say.
+ */
+export function formatPolicySegment(p) {
+    if (!p)
+        return undefined;
+    const parts = [];
+    if (p.envScope !== undefined)
+        parts.push(p.envScope ? "env scoped" : "env unscoped");
+    if (p.sandbox) {
+        parts.push(p.sandbox.mode === "off"
+            ? "sandbox off"
+            : p.sandbox.started
+                ? "sandbox on"
+                : "sandbox unavailable (ran unsandboxed)");
+    }
+    if (p.outputs) {
+        const n = (count) => `${count} ${count === 1 ? "output" : "outputs"}`;
+        if (p.outputs.staged > 0)
+            parts.push(`${n(p.outputs.staged)} staged`);
+        if (p.outputs.applied > 0)
+            parts.push(`${n(p.outputs.applied)} applied`);
+    }
+    return parts.length > 0 ? `policy: ${parts.join(", ")}` : undefined;
+}
 export function formatReceiptDuration(ms) {
     if (ms < 1000)
         return `${Math.max(0, Math.round(ms))}ms`;
@@ -108,6 +154,7 @@ export function formatReceipt(s) {
         ...(s.costUsd !== undefined ? [formatCost(s.costUsd)] : []),
         ...(s.harness !== undefined && s.harness !== "claude-code" ? [s.harness] : []),
         ...(s.degraded && s.degraded.length > 0 ? [`degraded: ${s.degraded.join(", ")}`] : []),
+        ...(formatPolicySegment(s.policy) ? [formatPolicySegment(s.policy)] : []),
         ...(s.budget ? [formatBudgetOverrun(s.budget)] : []),
     ];
     return parts.join(" · ");

package/dist/cli/templates.js

@@ -31,7 +31,33 @@ nodes:
       From the survey, write a short plain-English explanation:
       what this project does, how it is organized, how to build and
       run it, and where a new contributor should start.
-      Keep it under 300 words.
+      Keep every field short and concrete: a sentence or a few
+      bullets, in plain English, naming real files and commands.
+    output:
+      type: object
+      properties:
+        purpose:
+          type: string
+          title: What it is
+          description: One or two sentences on what this project does and who it is for.
+        how_to_run:
+          type: array
+          title: How to run it
+          description: The commands, in order, to install, build, test, and start it.
+          items:
+            type: string
+        key_files:
+          type: array
+          title: Key files
+          description: The files and directories a new contributor should open first, each with a few words on why.
+          items:
+            type: string
+        risks:
+          type: array
+          title: Watch out for
+          description: Sharp edges, missing docs, or things that look fragile. Empty if none.
+          items:
+            type: string
 
 edges:
   - from: survey

package/dist/cli/workflow-upgrade.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `sweny workflow upgrade <file> [--dry-run]`
+ *
+ * Rewrites a workflow file at the current spec version by running the same
+ * migration chain the loader applies in memory.
+ *
+ * Comment preservation (YAML): the file is edited as a YAML document, not
+ * re-serialized from scratch. Comments, blank lines, key order and quoting on
+ * everything a migration did not touch are kept. NOT preserved: a comment
+ * attached to a value a migration replaced or removed, the original position of
+ * keys a migration renamed (they are added at the end of their map), and
+ * formatting of arrays whose length a migration changed (rewritten whole).
+ * JSON files carry no comments and are rewritten with 2-space indentation.
+ */
+import { type MigrationConfig } from "../migrations.js";
+export type UpgradeResult = {
+    status: "error";
+    message: string;
+} | {
+    status: "current";
+    version: number;
+} | {
+    status: "upgraded" | "dry-run";
+    from: number;
+    to: number;
+    /** Migration descriptions applied, in order. Empty when only `spec_version` was stamped. */
+    steps: string[];
+    /** The full text that was (or, for dry-run, would be) written. */
+    content: string;
+};
+export interface UpgradeOptions {
+    dryRun?: boolean;
+    migration?: MigrationConfig;
+}
+export declare function upgradeWorkflowFile(filePath: string, options?: UpgradeOptions): UpgradeResult;

package/dist/cli/workflow-upgrade.js

@@ -0,0 +1,139 @@
+/**
+ * `sweny workflow upgrade <file> [--dry-run]`
+ *
+ * Rewrites a workflow file at the current spec version by running the same
+ * migration chain the loader applies in memory.
+ *
+ * Comment preservation (YAML): the file is edited as a YAML document, not
+ * re-serialized from scratch. Comments, blank lines, key order and quoting on
+ * everything a migration did not touch are kept. NOT preserved: a comment
+ * attached to a value a migration replaced or removed, the original position of
+ * keys a migration renamed (they are added at the end of their map), and
+ * formatting of arrays whose length a migration changed (rewritten whole).
+ * JSON files carry no comments and are rewritten with 2-space indentation.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isMap, parseDocument } from "yaml";
+import { DEFAULT_MIGRATION_CONFIG, migrateWorkflow } from "../migrations.js";
+import { validateParsed } from "../loader.js";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function withoutSpecVersion(obj) {
+    const copy = { ...obj };
+    delete copy.spec_version;
+    return copy;
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Apply the difference old -> next onto the YAML document, touching only what changed. */
+function applyDiff(doc, at, old, next) {
+    if (sameJson(old, next))
+        return;
+    if (isPlainObject(old) && isPlainObject(next)) {
+        for (const key of Object.keys(old)) {
+            if (!(key in next))
+                doc.deleteIn([...at, key]);
+        }
+        for (const key of Object.keys(next)) {
+            if (key in old)
+                applyDiff(doc, [...at, key], old[key], next[key]);
+            else
+                doc.setIn([...at, key], next[key]);
+        }
+        return;
+    }
+    if (Array.isArray(old) && Array.isArray(next) && old.length === next.length) {
+        next.forEach((item, i) => applyDiff(doc, [...at, i], old[i], item));
+        return;
+    }
+    if (at.length === 0)
+        doc.contents = doc.createNode(next);
+    else
+        doc.setIn(at, next);
+}
+function setSpecVersion(doc, version) {
+    const root = doc.contents;
+    if (!isMap(root))
+        return;
+    if (root.has("spec_version")) {
+        root.set("spec_version", version);
+        return;
+    }
+    // Insert as the first key. A comment sitting directly above the old first key
+    // is the file's header comment; carry it onto the new pair so it stays on top.
+    const first = root.items[0];
+    const pair = doc.createPair("spec_version", version);
+    const firstKey = first?.key;
+    if (firstKey && firstKey.commentBefore) {
+        pair.key.commentBefore = firstKey.commentBefore;
+        firstKey.commentBefore = undefined;
+    }
+    root.items.unshift(pair);
+}
+export function upgradeWorkflowFile(filePath, options = {}) {
+    const config = options.migration ?? DEFAULT_MIGRATION_CONFIG;
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        return { status: "error", message: `Could not read "${filePath}": ${err instanceof Error ? err.message : err}` };
+    }
+    const isYaml = [".yaml", ".yml"].includes(path.extname(filePath).toLowerCase());
+    let doc;
+    let raw;
+    try {
+        if (isYaml) {
+            doc = parseDocument(content);
+            if (doc.errors.length > 0)
+                throw doc.errors[0];
+            raw = doc.toJS();
+        }
+        else {
+            raw = JSON.parse(content);
+        }
+    }
+    catch (err) {
+        return { status: "error", message: `Could not parse "${filePath}": ${err instanceof Error ? err.message : err}` };
+    }
+    if (!isPlainObject(raw))
+        return { status: "error", message: `Expected a workflow object in "${filePath}"` };
+    const migrated = migrateWorkflow(raw, config);
+    if (!migrated.ok)
+        return { status: "error", message: migrated.message };
+    const versionText = String(migrated.to);
+    if (migrated.applied.length === 0 && raw.spec_version === versionText) {
+        return { status: "current", version: migrated.to };
+    }
+    // Never write a file that would not load.
+    const check = validateParsed(migrated.workflow, { migration: config });
+    if (!check.ok) {
+        return {
+            status: "error",
+            message: `The upgraded workflow is not valid, so "${filePath}" was left unchanged:\n${check.errors
+                .map((e) => `  ${e.message}`)
+                .join("\n")}`,
+        };
+    }
+    let out;
+    if (doc) {
+        applyDiff(doc, [], withoutSpecVersion(raw), withoutSpecVersion(migrated.workflow));
+        setSpecVersion(doc, versionText);
+        out = doc.toString();
+    }
+    else {
+        out = JSON.stringify({ spec_version: versionText, ...withoutSpecVersion(migrated.workflow) }, null, 2) + "\n";
+    }
+    if (!options.dryRun)
+        fs.writeFileSync(filePath, out, "utf-8");
+    return {
+        status: options.dryRun ? "dry-run" : "upgraded",
+        from: migrated.from,
+        to: migrated.to,
+        steps: migrated.applied.map((m) => m.description),
+        content: out,
+    };
+}

package/dist/harness/claude-code.d.ts

@@ -150,6 +150,8 @@ export declare class ClaudeCodeHarness implements Claude, AgentHarness {
     private sandboxProbe;
     private sandboxWarned;
     private envScope;
+    /** Floor facts from the latest runQuery, read by run() for the receipt. */
+    private lastPolicyFacts;
     private toolBridge;
     private toolBridgeShim;
     private authProbe;

package/dist/harness/claude-code.js

@@ -217,6 +217,8 @@ export class ClaudeCodeHarness {
     sandboxProbe;
     sandboxWarned = false;
     envScope;
+    /** Floor facts from the latest runQuery, read by run() for the receipt. */
+    lastPolicyFacts;
     toolBridge;
     toolBridgeShim;
     authProbe;
@@ -312,7 +314,12 @@ export class ClaudeCodeHarness {
             sandboxMode: policy.sandbox,
             agentAccess: { envVars: req.agentAccess?.envVars ?? [], domains: policy.egress, noPush: req.agentAccess?.noPush },
         });
-        return { ...result, harness: this.info(), degraded: gate.degraded };
+        return {
+            ...result,
+            harness: this.info(),
+            degraded: gate.degraded,
+            ...(this.lastPolicyFacts ? { policy: this.lastPolicyFacts } : {}),
+        };
     }
     async runQuery(opts) {
         const { instruction, context, tools, outputSchema, onProgress, maxTurns, model, timeoutMs, signal, readOnly, agentAccess, onUsage, } = opts;
@@ -334,6 +341,11 @@ export class ClaudeCodeHarness {
             probe: this.sandboxProbe,
             logger: this.logger,
         });
+        this.lastPolicyFacts = {
+            envScope: resolveEnvScope(process.env, this.envScope),
+            sandbox: sandbox.mode,
+            sandboxStarted: sandbox.settings !== undefined,
+        };
         if (sandbox.error) {
             this.logger.error(sandbox.error);
             return { status: "failed", data: { error: sandbox.error, refused: true }, toolCalls: [] };

package/dist/index.d.ts

@@ -45,6 +45,8 @@ export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, so
 export type { WorkflowError } from "./schema.js";
 export { loadAndValidateWorkflow, validateParsed } from "./loader.js";
 export type { LoaderResult, LoaderError, LoaderOptions } from "./loader.js";
+export { CURRENT_SPEC_VERSION, MIGRATIONS, migrateWorkflow } from "./migrations.js";
+export type { Migration, MigrationConfig, MigrateResult } from "./migrations.js";
 export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 export { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "./mcp.js";
 export type { ProviderContextOptions, SkillMcpOptions } from "./mcp.js";

package/dist/index.js

@@ -47,6 +47,7 @@ export { workflowZ, nodeZ, edgeZ, skillZ, mcpServerConfigZ, skillDefinitionZ, so
 // the CLI uses for `workflow run`, `workflow validate`, and `publish`).
 // Node-only: loader.ts imports `node:fs`, so this is NOT mirrored in browser.ts.
 export { loadAndValidateWorkflow, validateParsed } from "./loader.js";
+export { CURRENT_SPEC_VERSION, MIGRATIONS, migrateWorkflow } from "./migrations.js";
 // Workflow input validation
 export { validateRuntimeInput, summarizeInputShape } from "./inputs.js";
 // MCP auto-injection

package/dist/loader.d.ts

@@ -11,15 +11,18 @@
  */
 import type { Workflow } from "./types.js";
 import { type WorkflowError } from "./schema.js";
+import { type MigrationConfig } from "./migrations.js";
 /** Structural/schema error. `code` is present only for structural errors. */
 export interface LoaderError {
     message: string;
-    code?: WorkflowError["code"] | "IO" | "PARSE" | "SCHEMA";
+    code?: WorkflowError["code"] | "IO" | "PARSE" | "SCHEMA" | "SPEC_VERSION";
     nodeId?: string;
 }
 export type LoaderResult = {
     ok: true;
     workflow: Workflow;
+    /** Non-fatal notes, e.g. the one-line "migrated in memory" warning. */
+    warnings?: string[];
 } | {
     ok: false;
     errors: LoaderError[];
@@ -27,6 +30,10 @@ export type LoaderResult = {
 export interface LoaderOptions {
     /** Optional set of known skill IDs for UNKNOWN_SKILL validation. */
     knownSkills?: Set<string>;
+    /** Spec version + migration registry. Defaults to the built-in one; tests inject their own. */
+    migration?: MigrationConfig;
+    /** Path shown in the migration warning. Set by loadAndValidateWorkflow. */
+    filePath?: string;
 }
 /**
  * Load a workflow YAML or JSON file, parse with the canonical Zod schema,

package/dist/loader.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { workflowZ, validateWorkflow, preflightLegacyVerify } from "./schema.js";
+import { DEFAULT_MIGRATION_CONFIG, migrateWorkflow, migrationWarning, } from "./migrations.js";
 /**
  * Load a workflow YAML or JSON file, parse with the canonical Zod schema,
  * and run structural validation. All three phases contribute to `errors`.
@@ -36,7 +37,7 @@ export function loadAndValidateWorkflow(filePath, options = {}) {
         const msg = err instanceof Error ? err.message : String(err);
         return { ok: false, errors: [{ message: `Could not parse "${filePath}": ${msg}`, code: "PARSE" }] };
     }
-    return validateParsed(raw, options);
+    return validateParsed(raw, { ...options, filePath: options.filePath ?? filePath });
 }
 /**
  * Validate an already-parsed workflow object (e.g. from a marketplace fetch
@@ -47,6 +48,15 @@ export function validateParsed(raw, options = {}) {
         const kind = raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw;
         return { ok: false, errors: [{ message: `Expected a workflow object, got ${kind}`, code: "SCHEMA" }] };
     }
+    // Apply spec_version migrations in memory (older versions), or refuse a
+    // version newer than this build supports. Runs first so a migration can
+    // reshape a file before the checks below see it.
+    const migrated = migrateWorkflow(raw, options.migration ?? DEFAULT_MIGRATION_CONFIG);
+    if (!migrated.ok) {
+        return { ok: false, errors: [{ message: migrated.message, code: "SPEC_VERSION" }] };
+    }
+    raw = migrated.workflow;
+    const warnings = migrated.applied.length > 0 ? [migrationWarning(migrated.from, migrated.to, options.filePath)] : [];
     // Detect legacy `verify:` blocks (renamed to `eval:` in v0.2.0) before the
     // Zod parse. workflowZ is intentionally non-strict at the top level, so a
     // top-level `verify:` would be silently STRIPPED instead of surfacing the
@@ -83,5 +93,5 @@ export function validateParsed(raw, options = {}) {
             errors: structural.map((e) => ({ message: e.message, code: e.code, nodeId: e.nodeId })),
         };
     }
-    return { ok: true, workflow: parsed };
+    return warnings.length > 0 ? { ok: true, workflow: parsed, warnings } : { ok: true, workflow: parsed };
 }

package/dist/migrations.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Workflow spec versioning and migrations.
+ *
+ * Every workflow file carries an optional top-level `spec_version` (a string
+ * holding a positive integer, e.g. "1"). A file without the field is version 1:
+ * that is what every file written before the field existed means.
+ *
+ * Breaking spec changes bump CURRENT_SPEC_VERSION and add one entry to
+ * MIGRATIONS: a pure function from the raw (unvalidated) vN object to the raw
+ * vN+1 object. The loader applies the chain in memory so old files keep
+ * running; `sweny workflow upgrade <file>` writes the result back to disk.
+ *
+ * Adding a migration: see `__tests__/migrations.test.ts` for the harness
+ * (registry validity check plus a chain test to copy).
+ */
+/** A raw, not-yet-validated workflow object as parsed from YAML or JSON. */
+export type RawWorkflow = Record<string, unknown>;
+export interface Migration {
+    /** Version this migration reads. */
+    from: number;
+    /** Version it produces. Always `from + 1`. */
+    to: number;
+    /** One line shown by `sweny workflow upgrade`. */
+    description: string;
+    /** Pure: must not mutate its input. Returns the next-version object. */
+    migrate: (raw: RawWorkflow) => RawWorkflow;
+}
+/** The spec version this build of sweny reads natively. */
+export declare const CURRENT_SPEC_VERSION = 1;
+/**
+ * Ordered registry, one entry per version step. Empty while v1 is current.
+ * Append only; never edit a shipped migration.
+ */
+export declare const MIGRATIONS: readonly Migration[];
+export interface MigrationConfig {
+    current: number;
+    migrations: readonly Migration[];
+}
+export declare const DEFAULT_MIGRATION_CONFIG: MigrationConfig;
+export type MigrateError = {
+    code: "INVALID_VERSION" | "TOO_NEW" | "MIGRATION_FAILED";
+    message: string;
+};
+export type MigrateResult = {
+    ok: true;
+    /** The (possibly migrated) object. `spec_version` is a string when it was declared or migrated. */
+    workflow: RawWorkflow;
+    /** Version the file declared (1 when absent). */
+    from: number;
+    /** Version of `workflow` after migration. */
+    to: number;
+    /** Whether the input declared `spec_version`. */
+    declared: boolean;
+    /** Migrations applied, in order. Empty when the file is already current. */
+    applied: Migration[];
+} | ({
+    ok: false;
+} & MigrateError);
+/** Throws if a registry is not an unbroken chain of single steps ending at `current`. */
+export declare function assertRegistryValid(config: MigrationConfig): void;
+export declare function migrateWorkflow(raw: RawWorkflow, config?: MigrationConfig): MigrateResult;
+/** The single warning the loader emits when it migrated in memory. */
+export declare function migrationWarning(from: number, to: number, filePath?: string): string;

package/dist/migrations.js

@@ -0,0 +1,93 @@
+/**
+ * Workflow spec versioning and migrations.
+ *
+ * Every workflow file carries an optional top-level `spec_version` (a string
+ * holding a positive integer, e.g. "1"). A file without the field is version 1:
+ * that is what every file written before the field existed means.
+ *
+ * Breaking spec changes bump CURRENT_SPEC_VERSION and add one entry to
+ * MIGRATIONS: a pure function from the raw (unvalidated) vN object to the raw
+ * vN+1 object. The loader applies the chain in memory so old files keep
+ * running; `sweny workflow upgrade <file>` writes the result back to disk.
+ *
+ * Adding a migration: see `__tests__/migrations.test.ts` for the harness
+ * (registry validity check plus a chain test to copy).
+ */
+/** The spec version this build of sweny reads natively. */
+export const CURRENT_SPEC_VERSION = 1;
+/**
+ * Ordered registry, one entry per version step. Empty while v1 is current.
+ * Append only; never edit a shipped migration.
+ */
+export const MIGRATIONS = [];
+export const DEFAULT_MIGRATION_CONFIG = {
+    current: CURRENT_SPEC_VERSION,
+    migrations: MIGRATIONS,
+};
+/** Throws if a registry is not an unbroken chain of single steps ending at `current`. */
+export function assertRegistryValid(config) {
+    const { current, migrations } = config;
+    if (!Number.isInteger(current) || current < 1)
+        throw new Error("current spec version must be a positive integer");
+    if (migrations.length !== current - 1) {
+        throw new Error(`expected ${current - 1} migration(s) to reach v${current}, found ${migrations.length}`);
+    }
+    migrations.forEach((m, i) => {
+        if (m.from !== i + 1 || m.to !== i + 2) {
+            throw new Error(`migration #${i} must be v${i + 1} -> v${i + 2}, got v${m.from} -> v${m.to}`);
+        }
+    });
+}
+function parseVersion(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1)
+        return value;
+    if (typeof value === "string" && /^[1-9]\d*$/.test(value))
+        return Number(value);
+    return null;
+}
+export function migrateWorkflow(raw, config = DEFAULT_MIGRATION_CONFIG) {
+    const declared = "spec_version" in raw && raw.spec_version !== undefined;
+    const from = declared ? parseVersion(raw.spec_version) : 1;
+    if (from === null) {
+        return {
+            ok: false,
+            code: "INVALID_VERSION",
+            message: `spec_version must be a positive integer string like "1", got ${JSON.stringify(raw.spec_version)}`,
+        };
+    }
+    if (from > config.current) {
+        return {
+            ok: false,
+            code: "TOO_NEW",
+            message: `This workflow declares spec_version "${from}", but this version of sweny supports up to "${config.current}". ` +
+                `Upgrade sweny (run "sweny upgrade", or npm install -g @sweny-ai/core@latest) and try again.`,
+        };
+    }
+    let current = declared ? { ...raw, spec_version: String(from) } : raw;
+    const applied = [];
+    for (let v = from; v < config.current; v++) {
+        const step = config.migrations.find((m) => m.from === v);
+        if (!step) {
+            return { ok: false, code: "MIGRATION_FAILED", message: `No migration registered from spec_version "${v}".` };
+        }
+        try {
+            current = { ...step.migrate(current), spec_version: String(step.to) };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                code: "MIGRATION_FAILED",
+                message: `Migration from spec_version "${step.from}" to "${step.to}" failed: ${msg}`,
+            };
+        }
+        applied.push(step);
+    }
+    return { ok: true, workflow: current, from, to: config.current, declared, applied };
+}
+/** The single warning the loader emits when it migrated in memory. */
+export function migrationWarning(from, to, filePath) {
+    const target = filePath ? `"${filePath}"` : "<file>";
+    return (`Workflow uses spec_version "${from}" (current is "${to}"); migrated in memory for this run. ` +
+        `Run \`sweny workflow upgrade ${target}\` to update the file.`);
+}

package/dist/schema.d.ts

@@ -1714,6 +1714,7 @@ export declare const workflowZ: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodDefault<z.ZodString>;
+    spec_version: z.ZodOptional<z.ZodString>;
     workflow_type: z.ZodOptional<z.ZodEnum<["pr_review", "e2e_test", "content_generation", "monitor", "data_sync", "generic"]>>;
     nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
@@ -2876,6 +2877,7 @@ export declare const workflowZ: z.ZodObject<{
         type?: string | undefined;
     })[] | undefined;
     judge_model?: string | undefined;
+    spec_version?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
     context_mode?: "full" | "bounded" | undefined;
@@ -3064,6 +3066,7 @@ export declare const workflowZ: z.ZodObject<{
         type?: string | undefined;
     })[] | undefined;
     judge_model?: string | undefined;
+    spec_version?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
     context_mode?: "full" | "bounded" | undefined;
@@ -3266,6 +3269,7 @@ export declare function parseWorkflow(raw: unknown): {
         type?: string | undefined;
     })[] | undefined;
     judge_model?: string | undefined;
+    spec_version?: string | undefined;
     workflow_type?: "pr_review" | "e2e_test" | "content_generation" | "monitor" | "data_sync" | "generic" | undefined;
     judge_budget?: number | undefined;
     context_mode?: "full" | "bounded" | undefined;
@@ -3649,6 +3653,11 @@ export declare const workflowJsonSchema: {
         readonly description: {
             readonly type: "string";
         };
+        readonly spec_version: {
+            readonly type: "string";
+            readonly pattern: "^[1-9][0-9]*$";
+            readonly description: "Workflow spec version as a positive integer string. Absent means 1. Older versions are migrated in memory on load; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.";
+        };
         readonly entry: {
             readonly type: "string";
             readonly minLength: 1;

package/dist/schema.js

@@ -357,6 +357,10 @@ export const workflowZ = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
     description: z.string().default(""),
+    spec_version: z
+        .string()
+        .regex(/^[1-9]\d*$/, "spec_version must be a positive integer string")
+        .optional(),
     workflow_type: workflowTypeZ.optional(),
     nodes: z.record(nodeZ),
     edges: z.array(edgeZ),
@@ -954,6 +958,11 @@ export const workflowJsonSchema = {
         id: { type: "string", minLength: 1 },
         name: { type: "string", minLength: 1 },
         description: { type: "string" },
+        spec_version: {
+            type: "string",
+            pattern: "^[1-9][0-9]*$",
+            description: "Workflow spec version as a positive integer string. Absent means 1. Older versions are migrated in memory on load; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.",
+        },
         entry: { type: "string", minLength: 1, description: "ID of the entry node" },
         rules: {
             type: "array",

package/dist/types.d.ts

@@ -514,6 +514,8 @@ export interface Workflow {
     id: string;
     name: string;
     description: string;
+    /** Spec version, a positive integer string (e.g. "1"). Absent means "1". See `migrations.ts`. */
+    spec_version?: string;
     /** Optional. Defaults to "generic" when absent. Required on marketplace templates. */
     workflow_type?: WorkflowType;
     nodes: Record<string, Node>;
@@ -622,6 +624,11 @@ export interface NodeResult {
     };
     /** Opinions this run could not honor natively. Always empty for Claude Code. */
     degraded?: string[];
+    /**
+     * Agent floor this node actually ran under, for the run receipt. Set by the
+     * Claude Code harness only; absent for harnesses that do not report it.
+     */
+    policy?: NodePolicyFacts;
     /** Safe outputs (#365): what the write stage did with each intent. Absent when the node declares none. */
     outputs?: SafeOutputReceipt[];
     /**
@@ -631,6 +638,15 @@ export interface NodeResult {
      */
     budget?: BudgetOverrun;
 }
+/** Facts about the agent floor (scoped env, process sandbox) a node ran under. Booleans and a mode only. */
+export interface NodePolicyFacts {
+    /** The agent subprocess env was narrowed to the allowlist. */
+    envScope: boolean;
+    /** Requested sandbox mode. */
+    sandbox: "off" | "auto" | "strict";
+    /** The sandbox was enabled for this node (false under `off`, or `auto` on a host that cannot sandbox). */
+    sandboxStarted: boolean;
+}
 export interface ToolCall {
     tool: string;
     input: unknown;

package/package.json

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