@sweny-ai/core 0.1.123 → 0.1.125

package/dist/cli/config-file.js

@@ -32,6 +32,40 @@ export function loadDotenv(cwd = process.cwd()) {
         }
     }
 }
+/**
+ * `.sweny.yml` keys for the agent execution floor (#360) and the env var each
+ * maps to. The runtime (claude.ts / agent-env.ts) reads the env var, so the
+ * same knob works for the CLI, the Action and library callers.
+ */
+const AGENT_FILE_KEYS = [
+    [["env-passthrough", "env_passthrough"], "SWENY_ENV_PASSTHROUGH"],
+    [["env-scope", "env_scope"], "SWENY_ENV_SCOPE"],
+    [["sandbox"], "SWENY_SANDBOX"],
+    [["sandbox-allowed-domains", "sandbox_allowed_domains"], "SWENY_SANDBOX_ALLOWED_DOMAINS"],
+];
+/**
+ * Copy agent sandbox / env-passthrough settings from `.sweny.yml` into the
+ * environment. Real env vars win (same precedence as {@link loadDotenv}).
+ * YAML booleans arrive as "true"/"false", which the sandbox mode parser
+ * treats as on/off.
+ */
+export function applyAgentFileConfig(fileConfig, env = process.env) {
+    for (const [keys, envVar] of AGENT_FILE_KEYS) {
+        if (env[envVar] !== undefined)
+            continue;
+        for (const key of keys) {
+            const v = fileConfig[key];
+            if (Array.isArray(v) && v.length > 0) {
+                env[envVar] = v.join(",");
+                break;
+            }
+            if (typeof v === "string" && v) {
+                env[envVar] = v;
+                break;
+            }
+        }
+    }
+}
 /**
  * Search upward from `cwd` for `.sweny.yml` and parse it.
  * Scalar values are strings, list values (rules, context) are string arrays.
@@ -114,7 +148,7 @@ export const STARTER_CONFIG = `# .sweny.yml — SWEny project configuration
 # observability-provider: datadog        # datadog | sentry | cloudwatch | splunk | elastic | newrelic | loki | prometheus | pagerduty | heroku | opsgenie | vercel | supabase | netlify | fly | render | file
 # issue-tracker-provider: github-issues  # github-issues | linear | jira
 # source-control-provider: github        # github | gitlab
-# coding-agent-provider: claude          # claude | codex | gemini
+# coding-agent-provider: claude          # claude (the only supported agent)
 # notification-provider: console         # console | slack | teams | discord | email | webhook
 
 # ── Investigation ────────────────────────────────────────────────────
@@ -141,6 +175,13 @@ export const STARTER_CONFIG = `# .sweny.yml — SWEny project configuration
 # cloud-token: sweny_pk_...
 # Or set SWENY_CLOUD_TOKEN in your environment.
 
+# ── Agent sandbox ─────────────────────────────────────────────────────
+# See https://docs.sweny.ai/advanced/agent-sandbox/
+# sandbox: off                           # off (local default) | auto (CI default: sandbox if supported, else warn) | strict
+# sandbox-allowed-domains: [internal.example.com]   # extra hosts agent commands may reach
+# env-scope: off                         # off (local default: full env) | on (CI default: allowlist)
+# env-passthrough: [NPM_TOKEN]           # extra env vars the agent may see when scoped ("*" = all)
+
 # ── MCP servers ───────────────────────────────────────────────────────
 # Extend the coding agent with additional tools via MCP.
 # Value is a JSON object — each key is a server name you choose.

package/dist/cli/config.js

@@ -6,7 +6,7 @@ export function registerTriageCommand(program) {
     return program
         .command("triage")
         .description("Run the SWEny triage workflow")
-        .option("--agent <provider>", "Coding agent: claude (default), codex, gemini")
+        .option("--agent <provider>", "Coding agent: claude (the only supported agent)")
         .option("--coding-agent-provider <provider>", "Coding agent provider (alias for --agent)")
         .option("--observability-provider <provider>", "Observability provider (default: none)")
         .option("--issue-tracker-provider <provider>", "Issue tracker provider (default: github-issues)")
@@ -228,18 +228,12 @@ export function validateInputs(config) {
                 errors.push("Missing: ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN — get a key at https://console.anthropic.com");
             }
             break;
-        case "codex":
-            if (!config.openaiApiKey) {
-                errors.push("Missing: OPENAI_API_KEY — get a key at https://platform.openai.com/api-keys");
-            }
-            break;
-        case "gemini":
-            if (!config.geminiApiKey) {
-                errors.push("Missing: GEMINI_API_KEY or GOOGLE_API_KEY — get a key at https://aistudio.google.com/app/apikey");
-            }
-            break;
         default:
-            errors.push(`Unsupported coding agent provider: ${config.codingAgentProvider} (use claude, codex, or gemini)`);
+            // Honest --agent (#330): SWEny runs headless Claude Code only. Nothing
+            // dispatches on other values, so accepting them would silently run
+            // Claude under a different name.
+            errors.push(`Unsupported coding agent "${config.codingAgentProvider}": the only supported agent is "claude" ` +
+                `(headless Claude Code). Remove --agent / coding-agent-provider or set it to claude.`);
     }
     // Repository required unless all providers are file-based
     const allLocal = config.issueTrackerProvider === "file" && config.sourceControlProvider === "file";
@@ -656,7 +650,7 @@ export function registerImplementCommand(program) {
     return program
         .command("implement <issueId>")
         .description("Implement a fix for a specific issue and open a PR")
-        .option("--agent <provider>", "Coding agent: claude (default), codex, gemini")
+        .option("--agent <provider>", "Coding agent: claude (the only supported agent)")
         .option("--coding-agent-provider <provider>", "Coding agent provider (alias for --agent)")
         .option("--issue-tracker-provider <provider>", "Issue tracker (linear|jira|github-issues|file)")
         .option("--source-control-provider <provider>", "Source control (github|gitlab|file)")
@@ -701,7 +695,10 @@ function parseMcpServers(json) {
 }
 function detectRepository() {
     try {
-        const remote = execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+        const remote = execSync("git remote get-url origin", {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         const match = remote.match(/[:/]([^/]+\/[^/.]+?)(?:\.git)?$/);
         return match?.[1] ?? "";
     }

package/dist/cli/e2e.d.ts

@@ -75,6 +75,28 @@ export interface E2eInitOptions {
  * then generates .sweny/e2e/*.yml and .env additions.
  */
 export declare function runE2eInit(options?: E2eInitOptions): Promise<void>;
+/**
+ * Default wall-clock budget (60 min) for a single workflow run when the
+ * caller doesn't pass `--timeout`. `--timeout 0` disables it. Shared by the e2e batch runner and the primary
+ * `sweny workflow run <file>` path (see main.ts workflowRunAction) so both
+ * fail loudly on a wedged node instead of hanging CI indefinitely. See #325.
+ */
+export declare const DEFAULT_WORKFLOW_TIMEOUT_MS: number;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string, onTimeout?: () => void): Promise<T>;
+/**
+ * Run a workflow execution under a whole-run wall-clock budget, aborting the
+ * in-flight run via `AbortSignal` when the budget is exceeded.
+ *
+ * Shared by the `.sweny/e2e/` batch runner (below) and the primary
+ * `sweny workflow run <file>` path (main.ts `workflowRunAction`) so both
+ * paths get the same abort/timeout behavior from one implementation instead
+ * of main.ts re-deriving it. Before #325, `workflowRunAction` never wired
+ * `--timeout` or an abort signal into `execute()` at all: a wedged node
+ * (hung tool call, runaway model turn) could hang the primary run path
+ * indefinitely even though the abort/timeout plumbing already existed in
+ * the executor and `claude.run`.
+ */
+export declare function runWithWallClockBudget<T>(run: (signal: AbortSignal) => Promise<T>, timeoutMs: number, label: string): Promise<T>;
 export interface E2eRunOptions {
     file?: string;
     timeout?: number;

package/dist/cli/e2e.js

@@ -481,6 +481,7 @@ export function buildFlowWorkflow(flow, baseUrl, cleanup) {
         id: `e2e-${flow.type}`,
         name: `E2E: ${typeName}`,
         description: `End-to-end test for ${flow.type} flow`,
+        workflow_type: "e2e_test",
         entry: "setup",
         nodes,
         edges,
@@ -760,7 +761,14 @@ export async function runE2eInit(options = {}) {
     }
 }
 // ── Timeout helper ─────────────────────────────────────────────────────
-function withTimeout(promise, ms, label, onTimeout) {
+/**
+ * Default wall-clock budget (60 min) for a single workflow run when the
+ * caller doesn't pass `--timeout`. `--timeout 0` disables it. Shared by the e2e batch runner and the primary
+ * `sweny workflow run <file>` path (see main.ts workflowRunAction) so both
+ * fail loudly on a wedged node instead of hanging CI indefinitely. See #325.
+ */
+export const DEFAULT_WORKFLOW_TIMEOUT_MS = 60 * 60 * 1000;
+export function withTimeout(promise, ms, label, onTimeout) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             // Abort the underlying work first so it stops advancing and the in-flight
@@ -775,6 +783,26 @@ function withTimeout(promise, ms, label, onTimeout) {
             .finally(() => clearTimeout(timer));
     });
 }
+/**
+ * Run a workflow execution under a whole-run wall-clock budget, aborting the
+ * in-flight run via `AbortSignal` when the budget is exceeded.
+ *
+ * Shared by the `.sweny/e2e/` batch runner (below) and the primary
+ * `sweny workflow run <file>` path (main.ts `workflowRunAction`) so both
+ * paths get the same abort/timeout behavior from one implementation instead
+ * of main.ts re-deriving it. Before #325, `workflowRunAction` never wired
+ * `--timeout` or an abort signal into `execute()` at all: a wedged node
+ * (hung tool call, runaway model turn) could hang the primary run path
+ * indefinitely even though the abort/timeout plumbing already existed in
+ * the executor and `claude.run`.
+ */
+export async function runWithWallClockBudget(run, timeoutMs, label) {
+    const controller = new AbortController();
+    // timeoutMs <= 0 means no wall-clock budget (`--timeout 0`).
+    if (!(timeoutMs > 0))
+        return run(controller.signal);
+    return withTimeout(run(controller.signal), timeoutMs, label, () => controller.abort());
+}
 /**
  * Policy for a no-file batch run. Pure so it can be unit-tested without
  * touching the filesystem, stdin, or the engine.
@@ -794,7 +822,7 @@ export function batchRunDecision(opts) {
  */
 export async function runE2eRun(options) {
     const cwd = process.cwd();
-    const timeoutMs = options.timeout || 15 * 60 * 1000;
+    const timeoutMs = options.timeout ?? DEFAULT_WORKFLOW_TIMEOUT_MS;
     // 1. Discover workflow files
     let files;
     if (options.file) {
@@ -911,9 +939,8 @@ export async function runE2eRun(options) {
                 }
             }
         };
-        const controller = new AbortController();
         try {
-            const { results } = await withTimeout(execute(workflow, { run_id: vars.run_id, base_url: vars.base_url }, { skills, claude, observer, logger: consoleLogger, signal: controller.signal }), timeoutMs, `Workflow ${workflow.name}`, () => controller.abort());
+            const { results } = await runWithWallClockBudget((signal) => execute(workflow, { run_id: vars.run_id, base_url: vars.base_url }, { skills, claude, observer, logger: consoleLogger, signal }), timeoutMs, `Workflow ${workflow.name}`);
             // Extract report
             const report = results.get("report");
             if (report?.data) {

package/dist/cli/main.d.ts

@@ -7,6 +7,7 @@ export declare function workflowRunAction(file: string | undefined, options: Rec
     mermaid?: boolean;
     verbose?: boolean;
     timeout?: string;
+    maxSteps?: string;
     yes?: boolean;
 }): Promise<void>;
 export declare function workflowExportAction(name: string): void;

package/dist/cli/main.js

@@ -10,26 +10,29 @@ import { execute } from "../executor.js";
 import { triageWorkflow, implementWorkflow, seedContentWorkflow } from "../workflows/index.js";
 import { consoleLogger } from "../types.js";
 import { ClaudeClient } from "../claude.js";
-import { createSkillMap, validateWorkflowSkills } from "../skills/index.js";
+import { builtinSkills, createSkillMap, validateWorkflowSkills } from "../skills/index.js";
+import { formatMissingSkillLines, skillEnvWarnings } from "./skill-env.js";
 import { configuredSkills, configuredSkillsWithDiagnostics } from "../skills/custom-loader.js";
 import { buildAutoMcpServers, buildSkillMcpServers, buildProviderContext } from "../mcp.js";
 import { loadAdditionalContext } from "../templates.js";
 import { loadAndValidateWorkflow } from "../loader.js";
 import { validateRuntimeInput } from "../inputs.js";
+import { mergeDryRunIntoInput, parseRunBudgetFlags } from "./workflow-input.js";
 import { stringify as stringifyYaml } from "yaml";
 import { buildWorkflow, refineWorkflow } from "../workflow-builder.js";
 import { toMermaidBlock } from "../mermaid.js";
 import { runWorkflowDiagram } from "./diagram.js";
 import { DagRenderer } from "./renderer.js";
 import * as readline from "node:readline";
-import { loadDotenv, loadConfigFile } from "./config-file.js";
+import { loadDotenv, loadConfigFile, applyAgentFileConfig } from "./config-file.js";
 import { buildCredentialMap } from "./credentials.js";
-import { runNew } from "./new.js";
-import { runE2eRun } from "./e2e.js";
+import { nonInteractiveUsage, runNew } from "./new.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";
 import { registerTriageCommand, registerImplementCommand, parseCliInputs, validateInputs, validateWarnings, parsePositiveInt, } from "./config.js";
 import { c, formatBanner, getStepDetails, formatStepLine, formatDagResultHuman, formatDagResultMarkdown, formatResultJson, formatValidationErrors, formatCrashError, formatCheckResults, } from "./output.js";
-import { checkProviderConnectivity } from "./check.js";
+import { checkProviderConnectivity, detectClaudeCodeLogin, discoverWorkflowSkillIds, validateCheckInputs, } from "./check.js";
 import { registerSetupCommand } from "./setup.js";
 import { registerPublishCommand } from "./publish.js";
 import { registerSkillCommand } from "./skill.js";
@@ -64,6 +67,8 @@ function composeObservers(...observers) {
 }
 // Auto-load .env before Commander parses (so env vars are available for defaults)
 loadDotenv();
+// Agent sandbox / env-passthrough keys from .sweny.yml -> SWENY_* env (#360).
+applyAgentFileConfig(loadConfigFile());
 const program = new Command()
     .name("sweny")
     .description("SWEny CLI \u2014 autonomous engineering workflows")
@@ -71,9 +76,17 @@ const program = new Command()
 // ── sweny new ─────────────────────────────────────────────────────────
 program
     .command("new [id]")
-    .description("Create a new workflow. With no id, opens the interactive picker. With an id, installs that workflow from the marketplace (swenyai/workflows).")
-    .action(async (id) => {
-    await runNew(id ? { marketplaceId: id } : undefined);
+    .description("Create a new workflow. With no id, opens the interactive picker. With an id, uses that built-in template, or installs it from the marketplace (swenyai/workflows).")
+    .option("--template <id>", "Use a built-in template without the picker")
+    .option("-y, --yes", "Skip every prompt (never overwrites existing files)")
+    .action(async (id, options) => {
+    // Prompts need a terminal. Without one (CI, pipes), a prompt never
+    // settles, so print usage and exit 2 instead of hanging.
+    if (!options.yes && !process.stdin.isTTY) {
+        console.error(nonInteractiveUsage());
+        process.exit(2);
+    }
+    await runNew({ marketplaceId: id, template: options.template, yes: options.yes });
 });
 // ── sweny check ───────────────────────────────────────────────────────
 program
@@ -82,13 +95,16 @@ program
     .action(async () => {
     const fileConfig = loadConfigFile();
     const config = parseCliInputs({}, fileConfig);
-    const errors = validateInputs(config);
+    const workflows = discoverWorkflowSkillIds(process.cwd());
+    const scope = workflows.found ? workflows.skillIds : undefined;
+    const claudeCodeLogin = detectClaudeCodeLogin();
+    const errors = validateCheckInputs(config, { scope, claudeCodeLogin });
     if (errors.length > 0) {
         console.error(formatValidationErrors(errors));
         process.exit(1);
     }
     console.log(chalk.dim("\n  Checking provider connectivity…\n"));
-    const results = await checkProviderConnectivity(config);
+    const results = await checkProviderConnectivity(config, { scope, claudeCodeLogin });
     console.log(formatCheckResults(results));
     const hasFailure = results.some((r) => r.status === "fail");
     process.exit(hasFailure ? 1 : 0);
@@ -418,17 +434,33 @@ triageCmd.action(async (options) => {
         process.exit(hasFailed ? 1 : 0);
     }
     catch (error) {
+        const crashMsg = error instanceof Error ? error.message : "Unknown error";
         if (config.json) {
-            console.log(JSON.stringify({ error: error instanceof Error ? error.message : "Unknown error" }));
+            console.log(JSON.stringify({ error: crashMsg }));
         }
         else {
             console.error(formatCrashError(error));
         }
+        // Finalize the cloud run as failed. execute() threw (including the
+        // RouteEvaluationError the executor raises on route-eval failure), so
+        // the in-try finish never ran and the run would otherwise stay stuck at
+        // "running" forever. No results map exists on this path, so pass an empty
+        // one; the error summary is a short message, never raw agent prose.
+        try {
+            // PRIVACY: pass the raw error, not crashMsg. finishCloudLifecycle reduces it
+            // to error.name + a 200-char message: thrown messages can embed agent/LLM
+            // prose or log text, and the cloud gets metadata only. It also sends at
+            // most one finish per run, so a throw after the in-try finish cannot
+            // overwrite the real result with a second "failed".
+            await finishCloudLifecycle(config, cloudHandle, new Map(), Date.now() - runStart, "failed", error);
+        }
+        catch {
+            // silent — cloud reporting must never block or mask the crash
+        }
         // Best-effort GitHub Actions step summary on crash
         if (config.notificationProvider === "github-summary" && process.env.GITHUB_STEP_SUMMARY) {
             try {
-                const msg = error instanceof Error ? error.message : "Unknown error";
-                fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `## ❌ SWEny Triage Crashed\n\n\`\`\`\n${msg}\n\`\`\`\n`);
+                fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `## ❌ SWEny Triage Crashed\n\n\`\`\`\n${crashMsg}\n\`\`\`\n`);
             }
             catch {
                 // ignore
@@ -589,7 +621,22 @@ implementCmd.action(async (issueId, options) => {
         process.exit(0);
     }
     catch (err) {
-        console.error(chalk.red(`\n  Error: ${err instanceof Error ? err.message : String(err)}\n`));
+        const crashMsg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`\n  Error: ${crashMsg}\n`));
+        // Finalize the cloud run as failed (covers thrown errors, incl.
+        // RouteEvaluationError). Without this a crashed implement run stays
+        // "running" in cloud forever.
+        try {
+            // PRIVACY: pass the raw error, not crashMsg. finishCloudLifecycle reduces it
+            // to error.name + a 200-char message: thrown messages can embed agent/LLM
+            // prose or log text, and the cloud gets metadata only. It also sends at
+            // most one finish per run, so a throw after the in-try finish cannot
+            // overwrite the real result with a second "failed".
+            await finishCloudLifecycle(config, implCloudHandle, new Map(), Date.now() - implRunStart, "failed", err);
+        }
+        catch {
+            // silent
+        }
         process.exit(1);
     }
 });
@@ -612,12 +659,22 @@ export function loadWorkflowFile(filePath, knownSkills) {
     return result.workflow;
 }
 export async function workflowRunAction(file, options) {
+    // Reject junk --timeout/--max-steps up front (both paths) instead of
+    // silently falling back to a default.
+    let budget;
+    try {
+        budget = parseRunBudgetFlags(options.timeout, options.maxSteps, DEFAULT_WORKFLOW_TIMEOUT_MS);
+    }
+    catch (err) {
+        console.error(chalk.red(`\n  ${err instanceof Error ? err.message : String(err)}\n`));
+        process.exit(1);
+    }
     // No file given → batch-run the e2e workflows in .sweny/e2e/. This is the
     // home for what used to be `sweny e2e run`; it lists what will run and
     // confirms first (bypass with --yes).
     if (!file) {
         await runE2eRun({
-            timeout: options.timeout ? parseInt(options.timeout, 10) : undefined,
+            timeout: options.timeout === undefined ? undefined : budget.timeoutMs,
             yes: Boolean(options.yes),
         });
         return;
@@ -631,7 +688,9 @@ export async function workflowRunAction(file, options) {
     for (const w of earlySkillDiscovery.warnings) {
         console.error(chalk.yellow(`  ⚠  ${w.message}`));
     }
-    const knownSkillIds = new Set(earlySkillDiscovery.skills.map((s) => s.id));
+    // A built-in skill with unset env is not "unknown": include every built-in id
+    // so the loader only flags genuine typos; missing env is reported below.
+    const knownSkillIds = new Set([...earlySkillDiscovery.skills.map((s) => s.id), ...builtinSkills.map((s) => s.id)]);
     let workflow;
     try {
         workflow = loadWorkflowFile(file, knownSkillIds);
@@ -663,23 +722,16 @@ export async function workflowRunAction(file, options) {
     // we require at least one configured skill per category.
     const validation = validateWorkflowSkills(workflow, skills, workflow.skills);
     if (validation.errors.length > 0) {
-        console.error(chalk.red(`\n  Workflow cannot run — missing required skills:\n`));
-        for (const err of validation.errors)
-            console.error(chalk.red(`    \u2717 ${err}`));
+        console.error(chalk.red(`\n  Workflow cannot run:\n`));
+        for (const line of formatMissingSkillLines(validation))
+            console.error(chalk.red(`    \u2717 ${line}`));
         const unknown = validation.missing.filter((m) => m.category === "unknown");
-        const envGaps = validation.missing.filter((m) => m.category !== "unknown" && m.missingEnv.length > 0);
         if (unknown.length > 0) {
             console.error(chalk.dim(`\n  These skill IDs aren't built-in or discovered in .{claude,sweny,agents,gemini}/skills/.\n  Scaffold one with:\n`));
             for (const m of unknown) {
                 console.error(chalk.dim(`    sweny skill new ${m.id}`));
             }
         }
-        if (envGaps.length > 0) {
-            console.error(chalk.dim(`\n  These skills are built-in but their env vars aren't set:`));
-            for (const m of envGaps) {
-                console.error(chalk.dim(`    - ${m.id}: ${m.missingEnv.join(", ")}`));
-            }
-        }
         console.error(chalk.dim(`\n  Run \`sweny skill list\` to see what's available.\n`));
         process.exit(1);
         return;
@@ -698,10 +750,12 @@ export async function workflowRunAction(file, options) {
         credentials: buildCredentialMap(),
         userMcpServers: Object.keys(config.mcpServers).length > 0 ? config.mcpServers : undefined,
     });
+    // Raw [info]/[debug] lines are verbose-only; warnings are rendered (#383).
+    const runLogger = createRunLogger({ verbose: Boolean(options.verbose), tty: isTTY });
     const claude = new ClaudeClient({
         maxTurns: config.maxInvestigateTurns || 50,
         cwd: process.cwd(),
-        logger: consoleLogger,
+        logger: runLogger,
         mcpServers,
         model: workflow.model,
     });
@@ -733,6 +787,7 @@ export async function workflowRunAction(file, options) {
                     else {
                         process.stderr.write(`  ${icon} ${event.node}  ${elapsed}\n`);
                     }
+                    runLogger.flush();
                     break;
                 }
                 case "workflow:end":
@@ -775,7 +830,7 @@ export async function workflowRunAction(file, options) {
             process.exit(1);
             return;
         }
-        workflowInput = validated.value;
+        workflowInput = mergeDryRunIntoInput(validated.value, config.dryRun);
     }
     else {
         workflowInput = {
@@ -827,18 +882,31 @@ export async function workflowRunAction(file, options) {
         console.log(c.subtle(`  cloud: ${wfCloudHandle.dashboardUrl}`));
     }
     const observer = composeObservers(wfProgressObserver, 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)
+    // could hang the run indefinitely despite the abort/timeout plumbing
+    // existing in the executor. --timeout is a whole-run wall-clock budget,
+    // enforced by runWithWallClockBudget (shared with the .sweny/e2e/ batch
+    // runner in e2e.ts). Absent = DEFAULT_WORKFLOW_TIMEOUT_MS (60 min);
+    // `--timeout 0` = no wall-clock budget; junk is rejected above.
+    // --max-steps overrides the executor's own DEFAULT_MAX_STEPS when set.
+    const wfTimeoutMs = budget.timeoutMs;
+    const wfMaxSteps = budget.maxSteps;
     try {
-        const { results, trace } = await execute(workflow, workflowInput, {
+        const { results, trace } = await runWithWallClockBudget((signal) => execute(workflow, workflowInput, {
             skills,
             claude,
             observer,
-            logger: consoleLogger,
+            logger: runLogger,
             cwd: process.cwd(),
             env: process.env,
             fetchAuth: config.fetchAuth,
             offline: config.offline,
             fileRoot: config.fileRoot || undefined,
-        });
+            signal,
+            max_steps: wfMaxSteps,
+        }), wfTimeoutMs, `Workflow ${workflow.name}`);
         const wfDurationMs = Date.now() - runStart;
         const wfHasFailed = [...results.values()].some((r) => r.status === "failed");
         // Close the cloud lifecycle session BEFORE the JSON early-exit so
@@ -870,16 +938,37 @@ export async function workflowRunAction(file, options) {
         catch {
             // silent
         }
+        // Run receipt (metadata only) + optional $GITHUB_STEP_SUMMARY.
+        runLogger.flush();
+        const receipt = summarizeRun(results, wfDurationMs);
+        writeStepSummary(workflow, results, receipt, trace);
         if (wfHasFailed) {
-            console.error(chalk.red(`  Workflow failed\n`));
+            console.error(`  ${renderReceiptLine(receipt, isTTY)}\n`);
             process.exit(1);
             return;
         }
-        console.log(chalk.green(`  Workflow completed\n`));
+        console.log(`  ${renderReceiptLine(receipt, isTTY)}\n`);
         process.exit(0);
     }
     catch (err) {
-        console.error(chalk.red(`\n  Error: ${err instanceof Error ? err.message : String(err)}\n`));
+        const crashMsg = err instanceof Error ? err.message : String(err);
+        console.error(chalk.red(`\n  Error: ${crashMsg}\n`));
+        runLogger.flush();
+        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
+        // "running" in cloud forever.
+        try {
+            // PRIVACY: pass the raw error, not crashMsg. finishCloudLifecycle reduces it
+            // to error.name + a 200-char message: thrown messages can embed agent/LLM
+            // prose or log text, and the cloud gets metadata only. It also sends at
+            // most one finish per run, so a throw after the in-try finish cannot
+            // overwrite the real result with a second "failed".
+            await finishCloudLifecycle(config, wfCloudHandle, new Map(), Date.now() - runStart, "failed", err);
+        }
+        catch {
+            // silent
+        }
         process.exit(1);
     }
 }
@@ -904,12 +993,21 @@ export function workflowExportAction(name) {
 }
 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())))
+        : [];
     if (options.json) {
         const errs = result.ok ? [] : result.errors;
-        process.stdout.write(JSON.stringify({ valid: result.ok, errors: errs }, null, 2) + "\n");
+        const payload = { valid: result.ok, errors: errs };
+        if (warnings.length > 0)
+            payload.warnings = warnings;
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     }
     else if (result.ok) {
         console.log(chalk.green(`  \u2713 ${file} is valid`));
+        for (const w of warnings)
+            console.error(chalk.yellow(`  \u26A0 ${w}`));
     }
     else {
         console.error(chalk.red(`  \u2717 ${file} has ${result.errors.length} validation error${result.errors.length > 1 ? "s" : ""}:`));
@@ -924,19 +1022,13 @@ workflowCmd
     .description("Validate a workflow YAML or JSON file")
     .option("--json", "Output result as JSON")
     .action(workflowValidateAction);
-workflowCmd
+const workflowRunCmd = workflowCmd
     .command("run [file]")
-    .description("Run a workflow from a YAML or JSON file. With no file, batch-runs every workflow in .sweny/e2e/ (lists and confirms first; use --yes to skip the prompt).")
-    .option("--timeout <ms>", "Per-workflow timeout in ms for batch runs (default: 900000 = 15 min)")
-    .option("-y, --yes", "Skip the batch confirmation prompt (for CI)")
-    .option("--dry-run", "Execute until the first conditional routing decision, then stop (no side effects past that point). NOTE: behavior changed in this release — previously --dry-run only printed the node list. For that behavior use --list-nodes.")
-    .option("--list-nodes", "Validate, print nodes/skills, and exit without running. (Replaces the pre-Fix-#6 --dry-run behavior.)")
-    .option("--json", "Output result as JSON on stdout; suppress progress output")
-    .option("--stream", "Stream NDJSON events to stdout (for Studio / automation)")
-    .option("--verbose", "Print each tool call's input and output inline (human-readable, truncated). Use --stream for full untruncated NDJSON.")
-    .option("--mermaid", "Output a Mermaid diagram with execution state after run")
-    .option("--input <json>", "JSON string of input data to pass to the workflow")
+    .description(WORKFLOW_RUN_DESCRIPTION)
     .action(workflowRunAction);
+for (const [flags, description] of WORKFLOW_RUN_OPTIONS) {
+    workflowRunCmd.option(flags, description);
+}
 workflowCmd
     .command("diagram <file>")
     .description("Render a workflow as a Mermaid diagram (raw .mmd by default; .md output auto-fences)")

package/dist/cli/marketplace.d.ts

@@ -24,7 +24,9 @@ export interface FetchedWorkflow {
     yaml: string;
 }
 export declare function fetchMarketplaceWorkflow(id: string): Promise<FetchedWorkflow>;
-export declare function fetchMarketplaceIndex(): Promise<MarketplaceEntry[]>;
+export declare function fetchMarketplaceIndex(opts?: {
+    timeoutMs?: number;
+}): Promise<MarketplaceEntry[]>;
 export interface ProviderMismatch {
     category: SkillCategory;
     configKey: string;

package/dist/cli/marketplace.js

@@ -46,11 +46,11 @@ export async function fetchMarketplaceWorkflow(id) {
     }
     return { id, yaml: await res.text() };
 }
-export async function fetchMarketplaceIndex() {
+export async function fetchMarketplaceIndex(opts = {}) {
     const url = `${MARKETPLACE_RAW_BASE}/index.json`;
     let res;
     try {
-        res = await fetch(url);
+        res = await fetch(url, opts.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : undefined);
     }
     catch {
         const err = new Error(`Could not reach github.com`);

package/dist/cli/new.d.ts

@@ -13,6 +13,8 @@ export interface Credential {
     hint?: string;
     url?: string;
     default?: string;
+    /** Written commented-out in .env (not needed in every setup). */
+    optional?: boolean;
 }
 export interface InitSelections {
     sourceControl: string;
@@ -118,6 +120,13 @@ 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.
+ */
+export declare function ensureGitignoreEnv(cwd: string): "created" | "appended" | "present";
+/** Usage printed (exit 2) when `sweny new` has no terminal and no --yes. */
+export declare function nonInteractiveUsage(): string;
 /**
  * Interactive workflow creation wizard — workflow-first approach.
  *
@@ -141,4 +150,10 @@ export declare function writeWorkflowFile(cwd: string, id: string, yaml: string,
 export declare function runNew(options?: {
     marketplaceId?: string;
     skipIntro?: boolean;
+    /** Built-in template id: skip the picker. */
+    template?: string;
+    /** Skip every confirmation prompt (never overwrites existing files). */
+    yes?: boolean;
+    /** Internal: the id came from the marketplace picker, skip the built-in shortcut. */
+    forceMarketplace?: boolean;
 }): Promise<void>;