@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/workflows.js

@@ -0,0 +1,1752 @@
+import { addCompactListReadFlags, appendCompactListReadQuery } from "../compact-list-flags.js";
+import { emitCliFailure, writeJson } from "../cli-output.js";
+import { CLI_MODULE_DIR } from "../cli-paths.js";
+import { parseJsonObject, readPositiveInt, readRecordString } from "../cli-values.js";
+import { collectMultiple, formatDisabledWorkflowNotices, parseJsonValue, readCsvOption, readPositiveNumber, writeListCapNotice } from "../command-support.js";
+import { addContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { importJavaScriptWorkflowModule, importTranspiledWorkflowModule, loadRecipeFromBundle } from "../local-module-loader.js";
+import { waitForCliRun } from "../run-wait.js";
+import { isRecord, readOption } from "../util.js";
+import { formatWorkflowPlanLimitNotices } from "../workflow-plan-limit-notices.js";
+import { WORKFLOW_RUN_LIST_FLAG_OVERLAY, readWorkflowRunListFlags } from "../workflow-run-list-flags.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { WORKFLOW_RUN_LIST_CONTRACT, workflowRunListQueryParams } from "@oxygen/shared/contracts/workflow-run-list";
+import { MAX_MCP_TOOL_NAME_LENGTH, workflowMcpToolName } from "@oxygen/shared/workflow-mcp-tools";
+import { assertRecipeBundleSafe, assertPortableWorkflowDefinition, assertWorkflowGraphManifest, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowGraphManifest, isWorkflowManifest, hashPortableWorkflowGraphManifest, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION } from "@oxygen/workflows";
+import { Command, Option } from "commander";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+const WORKFLOW_TAIL_DEFAULT_TIMEOUT_SECONDS = 600;
+const WORKFLOW_TAIL_DEFAULT_INTERVAL_SECONDS = 2;
+const RECIPE_ESBUILD_NODE_PATHS = [
+    resolve("node_modules"),
+    resolve("../../node_modules"),
+    resolve(CLI_MODULE_DIR, "../node_modules"),
+    resolve(CLI_MODULE_DIR, "../../../node_modules"),
+];
+function writeWorkflowPlanLimitNotices(data) {
+    for (const notice of formatWorkflowPlanLimitNotices(data)) {
+        process.stderr.write(`${notice}\n`);
+    }
+}
+function writeDisabledWorkflowNotices(data) {
+    for (const notice of formatDisabledWorkflowNotices(data)) {
+        process.stderr.write(`${notice}\n`);
+    }
+}
+// Arming a cron commits recurring spend, so `workflows enable` mirrors its
+// `automation` block as stderr lines: what the schedule burns per day in steps
+// and credits, what share of the monthly allowance that is, and when it runs
+// out. Observed burn (this workflow's own billed runs) is the honest number and
+// is preferred; the manifest floor is a MINIMUM and is labelled as one, because
+// recipe checkpoints and retries add steps. Writing rows is free.
+function writeAutomationProjection(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const automation = data.automation;
+    if (!automation || typeof automation !== "object" || Array.isArray(automation))
+        return;
+    const block = automation;
+    const estimate = block.estimate;
+    const observed = block.observed;
+    const allowance = block.allowance;
+    const runsPer30Days = typeof estimate?.scheduledRunsPer30Days === "number"
+        ? estimate.scheduledRunsPer30Days
+        : null;
+    if (runsPer30Days === null)
+        return; // On-demand: no schedule, no burn to project.
+    const projected = typeof observed?.projectedActionsPer30Days === "number"
+        ? observed.projectedActionsPer30Days
+        : typeof estimate?.scheduledActionsPer30DaysFloor === "number"
+            ? estimate.scheduledActionsPer30DaysFloor
+            : null;
+    if (projected === null)
+        return;
+    const fromHistory = typeof observed?.projectedActionsPer30Days === "number";
+    const perDay = Math.round(projected / 30);
+    const included = typeof allowance?.includedActions === "number" ? allowance.includedActions : null;
+    // A cheap schedule on a big plan rounds to "0% of the allowance", which reads
+    // as a bug rather than as reassurance. Floor the display at "<1%".
+    const sharePct = included !== null && included > 0 ? (projected / included) * 100 : null;
+    const share = sharePct === null
+        ? ""
+        : ` (${sharePct < 1 ? "<1" : Math.round(sharePct)}% of the ${included.toLocaleString("en-US")}/mo allowance)`;
+    const basis = fromHistory
+        ? `based on ${typeof observed?.runSample === "number" ? observed.runSample : 0} past billed runs`
+        : "MINIMUM — recipe checkpoints and retries can add steps";
+    // Older servers send no creditsPerStep; say nothing about credits rather than guess.
+    const creditsPerStep = typeof block.creditsPerStep === "number" ? block.creditsPerStep : null;
+    const credits = creditsPerStep === null
+        ? ""
+        : ` (~${(Math.round(projected * creditsPerStep * 100) / 3_000).toLocaleString("en-US", { maximumFractionDigits: 2 })} credits/day at ${creditsPerStep} per step; writing rows is free)`;
+    process.stderr.write(`schedule: ${runsPer30Days.toLocaleString("en-US")} runs/30d, ~${perDay.toLocaleString("en-US")} workflow steps/day${credits}${share}\n`);
+    process.stderr.write(`  ${basis}\n`);
+    const exhaustion = observed?.projectedExhaustionAt;
+    if (typeof exhaustion === "string") {
+        process.stderr.write(`  allowance runs out ${exhaustion} at this pace — the schedule pauses until the window resets\n`);
+    }
+}
+// `workflows apply` and `workflows enable` can return a non-blocking `warnings`
+// array (e.g. an aggressive cron cadence that still fits the plan's allowance).
+// Mirror each to stderr as one `warning: <message>` line — matching
+// writeAutomationProjection's stderr styling and keeping --json stdout clean.
+function writeScheduleWarnings(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const warnings = data.warnings;
+    if (!Array.isArray(warnings))
+        return;
+    for (const warning of warnings) {
+        if (typeof warning === "string" && warning.length > 0) {
+            process.stderr.write(`warning: ${warning}\n`);
+        }
+    }
+}
+// Shared human-output tail for the state-changing `workflows` commands (delete /
+// rename and the bulk enable/disable/delete summaries): print the response's
+// `next` action hints, then its deep link. Doctrine requires every state-changing
+// response to surface an oxygen-agent.com link in the terminal.
+function writeWorkflowActionTail(record) {
+    const next = Array.isArray(record.next) ? record.next : [];
+    for (const hint of next) {
+        if (typeof hint === "string" && hint.length > 0)
+            process.stdout.write(`${hint}\n`);
+    }
+    const link = typeof record.deepLink === "string"
+        ? record.deepLink
+        : typeof record.web_url === "string" ? record.web_url : null;
+    if (link)
+        process.stdout.write(`${link}\n`);
+}
+// Bulk `workflows enable | disable | delete` return a per-item results[] plus
+// summary counts. In human (non --json) output there is no JSON dump, so render
+// one readable line per item and a summary-count line to stdout. `okVerb` is the
+// past-tense success verb (enabled / disabled / deleted).
+function writeBulkWorkflowResults(data, okVerb) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const results = Array.isArray(record.results) ? record.results : [];
+    for (const entry of results) {
+        if (!isRecord(entry))
+            continue;
+        const ref = typeof entry.ref === "string" ? entry.ref : "workflow";
+        const workflow = isRecord(entry.workflow) ? entry.workflow : null;
+        const slug = workflow && typeof workflow.slug === "string" ? workflow.slug : ref;
+        if (typeof entry.skipped_reason === "string") {
+            process.stdout.write(`skipped ${slug}: ${entry.skipped_reason}\n`);
+        }
+        else if (entry.ok === true) {
+            process.stdout.write(`${okVerb} ${slug}\n`);
+        }
+        else {
+            const error = isRecord(entry.error) ? entry.error : null;
+            const message = error && typeof error.message === "string"
+                ? error.message
+                : error && typeof error.code === "string"
+                    ? error.code
+                    : "failed";
+            process.stdout.write(`failed ${slug}: ${message}\n`);
+        }
+    }
+    const counts = [];
+    for (const key of ["deleted", "enabled", "disabled", "skipped", "failed", "archived", "purged"]) {
+        const value = record[key];
+        if (typeof value === "number")
+            counts.push(`${value} ${key}`);
+    }
+    if (counts.length > 0)
+        process.stdout.write(`${counts.join(", ")}\n`);
+    writeWorkflowActionTail(record);
+}
+const WORKSPACE_EVENTS_HUMAN_LIMIT = 20;
+function workspaceEventFilterText(event) {
+    const filters = Array.isArray(event.filters) ? event.filters : [];
+    if (filters.length === 0)
+        return "all payloads";
+    return filters
+        .filter(isRecord)
+        .map((filter) => {
+        const path = typeof filter.path === "string" ? filter.path : "?";
+        const op = typeof filter.op === "string" ? filter.op : "?";
+        return filter.value === undefined ? `${path} ${op}` : `${path} ${op} ${String(filter.value)}`;
+    })
+        .join(" · ");
+}
+function formatWorkspaceEventsList(data) {
+    const events = Array.isArray(data.events) ? data.events.filter(isRecord) : [];
+    const total = typeof data.total === "number" ? data.total : events.length;
+    const availableTotal = typeof data.available_total === "number" ? data.available_total : total;
+    const builtin = typeof data.builtin_count === "number"
+        ? data.builtin_count
+        : events.filter((event) => event.kind === "builtin").length;
+    const integrations = typeof data.integration_count === "number"
+        ? data.integration_count
+        : events.filter((event) => event.kind === "integration").length;
+    const existing = typeof data.existing_count === "number"
+        ? data.existing_count
+        : events.filter((event) => event.kind === "existing").length;
+    const query = isRecord(data.query) ? data.query : {};
+    const queryParts = ["search", "source", "kind"].flatMap((key) => typeof query[key] === "string" ? [`${key}=${query[key]}`] : []);
+    const lines = [
+        total === availableTotal
+            ? `${total} workspace event${total === 1 ? "" : "s"} available`
+            : `${total} of ${availableTotal} workspace events matched`,
+        `${builtin} curated preset${builtin === 1 ? "" : "s"} · ${integrations} connected · ${existing} existing`,
+    ];
+    if (queryParts.length > 0)
+        lines.push(`Filters: ${queryParts.join(" · ")}`);
+    lines.push("");
+    if (events.length === 0) {
+        lines.push("No workspace events matched. Try a broader --search, or remove --source/--kind.");
+    }
+    else {
+        for (const event of events.slice(0, WORKSPACE_EVENTS_HUMAN_LIMIT)) {
+            const label = typeof event.label === "string"
+                ? event.label
+                : typeof event.event === "string" ? event.event : "Workspace event";
+            const kind = typeof event.kind === "string" ? event.kind : "event";
+            lines.push(`- ${label} [${kind}]`);
+            if (typeof event.catalogId === "string")
+                lines.push(`  catalog: ${event.catalogId}`);
+            const source = typeof event.source === "string" ? event.source : "?";
+            const eventName = typeof event.event === "string" ? event.event : "?";
+            lines.push(`  trigger: ${source}.${eventName} · ${workspaceEventFilterText(event)}`);
+            if (typeof event.description === "string")
+                lines.push(`  ${event.description}`);
+            const readiness = isRecord(event.readiness) ? event.readiness : null;
+            if (readiness?.status === "needs_setup") {
+                const reason = typeof readiness.reason === "string" ? readiness.reason : "Setup is required before this event can fire.";
+                lines.push(`  readiness: setup required — ${reason}`);
+                const action = isRecord(readiness.action) ? readiness.action : null;
+                if (action && typeof action.command === "string")
+                    lines.push(`  next: ${action.command}`);
+            }
+            else if (readiness?.status === "ready") {
+                lines.push("  readiness: ready");
+            }
+        }
+    }
+    if (events.length > WORKSPACE_EVENTS_HUMAN_LIMIT) {
+        lines.push("", `Showing ${WORKSPACE_EVENTS_HUMAN_LIMIT} of ${events.length}; narrow with --search, --source, or --kind. Use --json for every match.`);
+    }
+    lines.push("", "Inspect one: oxygen workflows events get <catalog-id>");
+    if (typeof data.web_url === "string")
+        lines.push(data.web_url);
+    return `${lines.join("\n")}\n`;
+}
+function formatWorkspaceEventDetail(data) {
+    const event = isRecord(data.event) ? data.event : null;
+    if (!event)
+        return `${JSON.stringify(data, null, 2)}\n`;
+    const label = typeof event.label === "string" ? event.label : String(event.event ?? "Workspace event");
+    const lines = [label];
+    if (typeof event.catalogId === "string")
+        lines.push(`Catalog: ${event.catalogId}`);
+    if (typeof event.group === "string")
+        lines.push(`Group: ${event.group}`);
+    if (typeof event.kind === "string")
+        lines.push(`Kind: ${event.kind}`);
+    if (typeof event.description === "string")
+        lines.push(`When it fires: ${event.description}`);
+    const readiness = isRecord(event.readiness) ? event.readiness : null;
+    if (readiness?.status === "ready")
+        lines.push("Readiness: ready");
+    if (readiness?.status === "needs_setup") {
+        lines.push(`Readiness: setup required${typeof readiness.reason === "string" ? ` — ${readiness.reason}` : ""}`);
+        const action = isRecord(readiness.action) ? readiness.action : null;
+        if (action && typeof action.command === "string")
+            lines.push(`Next: ${action.command}`);
+    }
+    if (isRecord(data.trigger)) {
+        lines.push("", "Trigger:", ...JSON.stringify(data.trigger, null, 2).split("\n").map((line) => `  ${line}`));
+    }
+    const payloadFields = Array.isArray(event.payloadFields)
+        ? event.payloadFields.filter((field) => typeof field === "string")
+        : [];
+    if (payloadFields.length > 0)
+        lines.push("", `Payload fields: ${payloadFields.join(", ")}`);
+    if (typeof data.web_url === "string")
+        lines.push("", data.web_url);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Map a workflow compile/validation throw to a typed `OxygenError`. The
+ * compiler and linter (`compileWorkflowDefinition`, `assertWorkflowManifest`,
+ * `serializeWorkflowFunction`, cron parsing) throw ordinary `Error`s shaped
+ * `"<code>: <message>"`, which `@oxygen/shared`'s `toFailure` would otherwise
+ * flatten to a machine-hostile `unexpected_error` — making `workflows lint`
+ * (whose whole job is to report authoring mistakes) read like an internal
+ * crash. Preserve the embedded lint code so the failure mirrors what a manifest
+ * lint would return (`duplicate_step_id`, `invalid_cron`, `invalid_max_credits`,
+ * …). Same precedent as `parseJsonValue`.
+ */
+function asWorkflowCompileError(error, filePath) {
+    if (error instanceof OxygenError)
+        return error;
+    const fsCode = error?.code;
+    if (typeof fsCode === "string" && /^E[A-Z]+$/.test(fsCode)) {
+        return new OxygenError("workflow_file_unreadable", `Could not read workflow file: ${error instanceof Error ? error.message : fsCode}`, { details: { file: filePath }, exitCode: 1 });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const match = /^([a-z][a-z0-9_]*): ([\s\S]+)$/.exec(message);
+    if (match?.[1] && match[2]) {
+        return new OxygenError(match[1], match[2], {
+            details: { file: filePath, phase: "compile" },
+            exitCode: 1,
+        });
+    }
+    return new OxygenError("invalid_workflow", message, {
+        details: { file: filePath, phase: "compile" },
+        exitCode: 1,
+    });
+}
+// ---- oxygen workflows init: graph-first authoring, recipe compatibility ----
+//
+// @oxygen/recipe-sdk is never published to npm — it ships bundled inside this CLI
+// (scripts/build-cli-npm-package.mjs → bundledDependencies). `init` vendors the SDK's
+// compiled type declarations into the user's project so their editor resolves
+// `@oxygen/recipe-sdk` (and the `@oxygen/workflows` types it re-exports) without an npm
+// install. We read the .d.ts from the same node paths esbuild uses to bundle the runtime
+// at `apply` time, so the vendored types stay locked to the CLI actually installed.
+const RECIPE_TYPES_VENDOR_DIR = ".oxygen/types";
+const RECIPE_INIT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/i;
+function renderStarterGraph(id, name, now = new Date()) {
+    const manifest = {
+        manifest_version: WORKFLOW_GRAPH_MANIFEST_VERSION,
+        workflow: { id, name, status: "disabled" },
+        trigger: { type: "api", status: "disabled" },
+        input_schema: { type: "object", properties: {} },
+        nodes: [{
+                id: "trigger",
+                name: "API trigger",
+                description: "Configure this trigger in the workflow editor.",
+                kind: "trigger",
+                ui: { x: 0, y: 0 },
+            }],
+        edges: [],
+        source_hash: "",
+        compiler_version: WORKFLOW_GRAPH_COMPILER_VERSION,
+        created_at: now.toISOString(),
+    };
+    manifest.source_hash = hashPortableWorkflowGraphManifest(manifest);
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+function scaffoldGraphProject(options) {
+    const workflowId = readOption(options.id) ?? "my-workflow";
+    if (!RECIPE_INIT_ID_PATTERN.test(workflowId)) {
+        throw new OxygenError("invalid_workflow_id", "Workflow id must start with a letter or digit and contain only letters, digits, dashes, or underscores.", {
+            details: { id: workflowId },
+            exitCode: 1,
+        });
+    }
+    const workflowName = readOption(options.name) ?? "My workflow";
+    const directory = resolve(readOption(options.dir) ?? ".");
+    const workflowFileName = `${workflowId}.workflow.json`;
+    const workflowFile = join(directory, workflowFileName);
+    const filesWritten = [];
+    const filesSkipped = [];
+    if (existsSync(workflowFile) && options.force !== true)
+        filesSkipped.push(workflowFile);
+    else {
+        mkdirSync(directory, { recursive: true });
+        writeFileSync(workflowFile, renderStarterGraph(workflowId, workflowName), "utf8");
+        filesWritten.push(workflowFile);
+    }
+    return {
+        format: "graph",
+        directory,
+        workflow_file: workflowFile,
+        files_written: filesWritten,
+        files_skipped: filesSkipped,
+        next_steps: [
+            `Edit ${workflowFileName}, then validate the draft: oxygen workflows lint --file ./${workflowFileName} --phase draft --json`,
+            `Save it without publishing: oxygen workflows apply --file ./${workflowFileName} --draft --json`,
+            `Inspect the saved draft: oxygen workflows revisions ${workflowId} --include-manifest --json`,
+            `Before publishing, validate readiness: oxygen workflows lint --file ./${workflowFileName} --phase publish --json`,
+        ],
+    };
+}
+function scaffoldWorkflowProject(options) {
+    return readOption(options.format) === "recipe"
+        ? scaffoldRecipeProject(options)
+        : scaffoldGraphProject(options);
+}
+function readBundledSdkDts(pkg) {
+    for (const base of RECIPE_ESBUILD_NODE_PATHS) {
+        const candidate = join(base, "@oxygen", pkg, "dist", "index.d.ts");
+        if (existsSync(candidate)) {
+            try {
+                return readFileSync(candidate, "utf8");
+            }
+            catch {
+                // Unreadable copy — fall through to the next node path.
+            }
+        }
+    }
+    return null;
+}
+function renderStarterRecipe(id, name) {
+    return [
+        'import { defineRecipe, type RecipeContext } from "@oxygen/recipe-sdk";',
+        "",
+        "// A durable recipe is the default export of defineRecipe(...); it compiles into an",
+        "// Oxygen workflow. Recipes reach external systems ONLY through catalog tools —",
+        "// raw fetch/network is disabled in the recipe sandbox.",
+        "//",
+        `// Deploy:  oxygen workflows apply --file ./${id}.ts`,
+        "// Dry-run: oxygen workflows call <workflow-id> --mode dry_run --json",
+        "// Docs:    https://oxygen-agent.com/docs/authoring/recipes",
+        "export default defineRecipe({",
+        `  id: ${JSON.stringify(id)},`,
+        `  name: ${JSON.stringify(name)},`,
+        "  // Allowlist of every tool id this recipe may call — including native table",
+        "  // ops, which dispatch through oxygen.* tools (e.g. oxygen.rows_upsert for",
+        "  // ctx.rows.upsert). Discover provider tools with: oxygen tools search <query>",
+        '  tools: ["firecrawl.scrape", "oxygen.rows_upsert"],',
+        '  trigger: { type: "api" },',
+        "  inputSchema: {",
+        '    type: "object",',
+        "    properties: {},",
+        "  },",
+        "  async run(ctx: RecipeContext) {",
+        '    ctx.log("info", "recipe started", { mode: ctx.mode });',
+        "    // Example: pull data through a tool, then persist it to a table.",
+        '    //   const page = await ctx.tools.run("firecrawl.scrape", { url }, { key: "scrape" });',
+        '    //   await ctx.rows.upsert("my_table", rows, { key: "save", upsertKey: "id" });',
+        "    return { ok: true, at: await ctx.now() };",
+        "  },",
+        "});",
+        "",
+    ].join("\n");
+}
+function renderRecipeTsconfig() {
+    const tsconfig = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            types: [],
+            // paths are resolved relative to this tsconfig (moduleResolution "Bundler"
+            // needs no baseUrl — and baseUrl is deprecated in TypeScript 6+).
+            paths: {
+                "@oxygen/recipe-sdk": [`./${RECIPE_TYPES_VENDOR_DIR}/@oxygen/recipe-sdk/index.d.ts`],
+                "@oxygen/workflows": [`./${RECIPE_TYPES_VENDOR_DIR}/@oxygen/workflows/index.d.ts`],
+            },
+        },
+        include: ["*.ts"],
+    };
+    return `${JSON.stringify(tsconfig, null, 2)}\n`;
+}
+function scaffoldRecipeProject(options) {
+    const recipeId = readOption(options.id) ?? "my-recipe";
+    if (!RECIPE_INIT_ID_PATTERN.test(recipeId)) {
+        throw new OxygenError("invalid_recipe_id", "Recipe id must start with a letter or digit and contain only letters, digits, dashes, or underscores.", {
+            details: { id: recipeId },
+            exitCode: 1,
+        });
+    }
+    const recipeName = readOption(options.name) ?? "My recipe";
+    const directory = resolve(readOption(options.dir) ?? ".");
+    const force = options.force === true;
+    const recipeDts = readBundledSdkDts("recipe-sdk");
+    const workflowsDts = readBundledSdkDts("workflows");
+    if (!recipeDts || !workflowsDts) {
+        throw new OxygenError("recipe_sdk_types_unavailable", "Could not locate the @oxygen/recipe-sdk types bundled with this CLI. Update the CLI (npm install -g @oxygen-agent/cli@latest) and retry.", { exitCode: 1 });
+    }
+    const recipeFileName = `${recipeId}.ts`;
+    const targets = [
+        { path: join(directory, recipeFileName), content: renderStarterRecipe(recipeId, recipeName) },
+        { path: join(directory, "tsconfig.json"), content: renderRecipeTsconfig() },
+        { path: join(directory, RECIPE_TYPES_VENDOR_DIR, "@oxygen", "recipe-sdk", "index.d.ts"), content: recipeDts },
+        { path: join(directory, RECIPE_TYPES_VENDOR_DIR, "@oxygen", "workflows", "index.d.ts"), content: workflowsDts },
+    ];
+    const filesWritten = [];
+    const filesSkipped = [];
+    for (const target of targets) {
+        if (existsSync(target.path) && !force) {
+            filesSkipped.push(target.path);
+            continue;
+        }
+        mkdirSync(dirname(target.path), { recursive: true });
+        writeFileSync(target.path, target.content, "utf8");
+        filesWritten.push(target.path);
+    }
+    return {
+        directory,
+        recipe_file: join(directory, recipeFileName),
+        files_written: filesWritten,
+        files_skipped: filesSkipped,
+        next_steps: [
+            `Edit ${recipeFileName}, then find tools with: oxygen tools search <query>`,
+            `Deploy it:  oxygen workflows apply --file ./${recipeFileName}`,
+            "Dry-run it: oxygen workflows call <workflow-id> --mode dry_run --json",
+        ],
+    };
+}
+function readPortableWorkflowDefinitionFile(filePath) {
+    const absolutePath = resolve(filePath);
+    let parsed;
+    try {
+        parsed = parseJsonValue(readFileSync(absolutePath, "utf8"), "--file");
+        assertPortableWorkflowDefinition(parsed);
+    }
+    catch (error) {
+        throw asWorkflowCompileError(error, filePath);
+    }
+    return parsed;
+}
+function parseWorkflowConnectionBindings(values) {
+    const result = {};
+    for (const value of values) {
+        const separator = value.indexOf("=");
+        const bindingId = separator > 0 ? value.slice(0, separator).trim() : "";
+        const connectionId = separator > 0 ? value.slice(separator + 1).trim() : "";
+        if (!bindingId || !connectionId) {
+            throw new OxygenError("invalid_workflow_connection_binding", `Invalid --connection '${value}'. Use <binding_id>=<connection_id>.`, { details: { value }, exitCode: 1 });
+        }
+        if (result[bindingId]) {
+            throw new OxygenError("duplicate_workflow_connection_binding", `Connection binding '${bindingId}' was provided more than once.`, { details: { binding_id: bindingId }, exitCode: 1 });
+        }
+        result[bindingId] = connectionId;
+    }
+    return result;
+}
+async function compileWorkflowFile(filePath) {
+    try {
+        return await loadWorkflowManifestFromFile(filePath);
+    }
+    catch (error) {
+        throw asWorkflowCompileError(error, filePath);
+    }
+}
+async function loadWorkflowManifestFromFile(filePath) {
+    const absolutePath = resolve(filePath);
+    const source = readFileSync(absolutePath, "utf8");
+    const extension = extname(absolutePath).toLowerCase();
+    if (extension === ".json") {
+        const parsed = parseJsonObject(source);
+        const manifest = isAnyWorkflowManifest(parsed)
+            ? parsed
+            : isAnyWorkflowManifest(parsed.manifest)
+                ? parsed.manifest
+                : null;
+        if (!manifest) {
+            const portable = parsed.kind === "oxygen-workflow-definition"
+                && parsed.definition_version === 1
+                && isRecord(parsed.graph);
+            throw new OxygenError("invalid_workflow_manifest", portable
+                ? `Detected a portable workflow export. Validate it without saving or running anything: oxygen workflows import --file ${filePath} --preflight --json. Workflows lint accepts authored manifests, not import envelopes.`
+                : "Workflow JSON must be a manifest or { manifest } object.", {
+                details: {
+                    file: filePath,
+                    ...(portable
+                        ? {
+                            detected_format: "oxygen-workflow-definition",
+                            next_command: `oxygen workflows import --file ${filePath} --preflight --json`,
+                        }
+                        : {}),
+                },
+                exitCode: 1,
+            });
+        }
+        if (isRecipeManifest(manifest))
+            return manifest;
+        // A v2 graph is nodes+edges, so the v1 linter would reject it with
+        // `invalid_manifest_version` — route it to its own linter instead. Without
+        // this the web canvas could author a graph the CLI could not apply, and the
+        // CLI is the primary surface.
+        if (isWorkflowGraphManifest(manifest)) {
+            const compiled = basename(absolutePath).endsWith(".workflow.json")
+                ? {
+                    ...manifest,
+                    created_at: new Date().toISOString(),
+                    source_hash: hashPortableWorkflowGraphManifest(manifest),
+                }
+                : manifest;
+            assertWorkflowGraphManifest(compiled);
+            return compiled;
+        }
+        assertWorkflowManifest(manifest);
+        return manifest;
+    }
+    if (extension !== ".js" && extension !== ".mjs" && extension !== ".ts") {
+        throw new OxygenError("invalid_workflow_file", "Workflow file must be .js, .mjs, .ts, or .json.", {
+            details: { file: filePath },
+            exitCode: 1,
+        });
+    }
+    const recipeManifest = await tryCompileRecipeFile(absolutePath, source);
+    if (recipeManifest)
+        return recipeManifest;
+    const mod = extension === ".ts"
+        ? await importTranspiledWorkflowModule(absolutePath, source)
+        : await importJavaScriptWorkflowModule(absolutePath, source);
+    const exported = mod.default ?? mod.workflow ?? mod.manifest;
+    if (isWorkflowDefinition(exported)) {
+        return compileWorkflowDefinition(exported, {
+            source,
+            sourceHash: createHash("sha256").update(source).digest("hex"),
+        });
+    }
+    if (isWorkflowManifest(exported)) {
+        assertWorkflowManifest(exported);
+        return exported;
+    }
+    throw new OxygenError("invalid_workflow_file", "Workflow module must export a workflow definition, recipe, or manifest.", {
+        details: { file: filePath },
+        exitCode: 1,
+    });
+}
+async function tryCompileRecipeFile(absolutePath, source) {
+    if (!referencesRecipeSdk(source))
+        return null;
+    const esbuild = await import("esbuild");
+    const result = await esbuild.build({
+        entryPoints: [absolutePath],
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "node",
+        target: "node22",
+        nodePaths: RECIPE_ESBUILD_NODE_PATHS,
+        minify: false,
+        sourcemap: false,
+        legalComments: "none",
+        logLevel: "silent",
+        metafile: true,
+    });
+    const out = result.outputFiles?.[0];
+    if (!out) {
+        throw new OxygenError("invalid_workflow_file", "esbuild produced no output for the recipe.", {
+            details: { file: absolutePath },
+            exitCode: 1,
+        });
+    }
+    const bundle = out.text;
+    try {
+        assertRecipeBundleSafe(bundle);
+    }
+    catch (error) {
+        throw new OxygenError("unsafe_recipe_bundle", error instanceof Error ? error.message : "Durable recipe bundle is unsafe.", {
+            details: { file: absolutePath },
+            exitCode: 1,
+        });
+    }
+    let recipe;
+    try {
+        recipe = await loadRecipeFromBundle(bundle, absolutePath);
+    }
+    catch (error) {
+        if (error instanceof OxygenError)
+            throw error;
+        throw new OxygenError("invalid_recipe_definition", error instanceof Error ? error.message : "Recipe definition is invalid.", {
+            details: { file: absolutePath },
+            exitCode: 1,
+        });
+    }
+    const sourceHash = createHash("sha256").update(bundle).digest("hex");
+    const manifest = buildRecipeManifest({
+        workflowId: recipe.id,
+        workflowName: recipe.name,
+        ...(recipe.status ? { status: recipe.status } : {}),
+        ...(recipe.trigger ? { trigger: recipe.trigger } : {}),
+        ...(recipe.inputSchema ? { inputSchema: recipe.inputSchema } : {}),
+        ...(recipe.visualPlan ? { visualPlan: recipe.visualPlan } : {}),
+        bundle,
+        toolsUsed: recipe.tools,
+        sourceHash,
+    });
+    return manifest;
+}
+function referencesRecipeSdk(source) {
+    return /["']@oxygen\/recipe-sdk["']/.test(source);
+}
+// The workflow tailer is the one bespoke wait surface: it POSTs (rather than
+// GETs a run by id), reads the run nested under the response envelope, and
+// carries the workflow/run/deep-link URLs from that envelope into its terminal
+// output. The shared waitForCliRun loop drives polling; this config injects the
+// workflow-specific fetch, terminal shape, and queued-no-worker timeout hint.
+function waitForWorkflowRun(runId, options) {
+    // Captured per poll so shapeTerminal can read the envelope-level URLs while
+    // fetchRun returns the nested run (where the status lives).
+    let latestEnvelope = {};
+    return waitForCliRun({
+        runId,
+        requestedTimeoutSeconds: options.timeoutSeconds,
+        requestedIntervalSeconds: options.intervalSeconds,
+        defaultTimeoutSeconds: WORKFLOW_TAIL_DEFAULT_TIMEOUT_SECONDS,
+        defaultIntervalSeconds: WORKFLOW_TAIL_DEFAULT_INTERVAL_SECONDS,
+        fetchRun: async () => {
+            latestEnvelope = await requestOxygen("/api/cli/workflows/run", {
+                method: "POST",
+                readOnly: true,
+                body: { run_id: runId },
+            });
+            return isRecord(latestEnvelope.run) ? latestEnvelope.run : latestEnvelope;
+        },
+        isTerminal: isTerminalWorkflowRunStatus,
+        shapeTerminal: (run, status, polls, elapsedMs) => {
+            const workflowUrl = readRecordString(latestEnvelope, "workflowUrl");
+            const runUrl = readRecordString(latestEnvelope, "runUrl");
+            const webUrl = readRecordString(latestEnvelope, "web_url");
+            const deepLink = readRecordString(latestEnvelope, "deepLink");
+            // `waiting` stops the poll but the run is NOT over — it resumes on its own
+            // at ready_at. Say so, and say when, or the caller reads `terminal: true`
+            // and concludes the run died.
+            const parked = status === "waiting";
+            const resumeAt = parked ? readRecordString(run, "readyAt") ?? readRecordString(run, "ready_at") : null;
+            return {
+                run,
+                workflowRunId: readRecordString(run, "id") ?? runId,
+                status,
+                terminal: !parked,
+                ...(parked
+                    ? {
+                        parked: true,
+                        ...(resumeAt ? { resumes_at: resumeAt } : {}),
+                        message: resumeAt
+                            ? `Run is parked until ${resumeAt} and resumes automatically — no action needed.`
+                            : "Run is parked and resumes automatically — no action needed.",
+                    }
+                    : {}),
+                polls,
+                elapsedMs,
+                ...(workflowUrl ? { workflowUrl } : {}),
+                ...(runUrl ? { runUrl } : {}),
+                ...(webUrl ? { web_url: webUrl } : {}),
+                ...(deepLink ? { deepLink } : {}),
+            };
+        },
+        timeoutCode: "workflow_tail_timeout",
+        timeoutMessage: "Timed out waiting for workflow run to finish.",
+        timeoutDetailIdKey: "workflow_run_id",
+        timeoutExtraDetails: (latestRun, status) => {
+            const worker = latestRun && isRecord(latestRun.worker) ? latestRun.worker : null;
+            const queuedWithoutWorker = status === "queued"
+                && worker !== null
+                && worker.active === null
+                && worker.lastClaim === null;
+            return queuedWithoutWorker
+                ? {
+                    worker_status: "queued_no_worker",
+                    guidance: "No worker has claimed this workflow run. Check `oxygen worker queue-stats --json` for Postgres-backed worker queue health.",
+                }
+                : {};
+        },
+    });
+}
+function workflowTemplateActionBody(templateId, options) {
+    const inputJson = readOption(options.inputJson);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    return {
+        template_id: templateId,
+        input: inputJson ? parseJsonObject(inputJson) : {},
+        ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+        ...(readOption(options.workflowId) ? { workflow_id: readOption(options.workflowId) } : {}),
+        ...(readOption(options.workflowName) ? { workflow_name: readOption(options.workflowName) } : {}),
+        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+// OXY-481: the deprecated `workflows templates {search,describe,preflight,apply}`
+// commands route through the canonical blueprint API. Map the legacy arg names
+// (template_id -> slug, --input-json -> inputs) and fold the old top-level
+// max_credits into inputs.max_credits, where seed blueprints read their cap.
+function workflowTemplateBlueprintBody(templateId, options, includeWorkflowOverrides = false) {
+    const inputJson = readOption(options.inputJson);
+    const inputs = inputJson ? parseJsonObject(inputJson) : {};
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    if (maxCredits !== undefined) {
+        inputs.max_credits = maxCredits;
+    }
+    const body = { slug: templateId, inputs };
+    if (includeWorkflowOverrides) {
+        const workflowId = readOption(options.workflowId);
+        if (workflowId)
+            body.workflow_id = workflowId;
+        const workflowName = readOption(options.workflowName);
+        if (workflowName)
+            body.workflow_name = workflowName;
+    }
+    return body;
+}
+function prepareWorkflowCliOutput(value, options) {
+    const normalized = normalizeWorkflowRunErrors(value);
+    return (options.includeBundle ? normalized : stripWorkflowBundles(normalized));
+}
+function stripWorkflowBundles(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => stripWorkflowBundles(entry));
+    if (!isRecord(value))
+        return value;
+    const shouldStripBundle = typeof value.bundle === "string"
+        && (value.runtime === "durable"
+            || value.bundle_format === "esm"
+            || (typeof value.compiler_version === "string" && value.compiler_version.startsWith("oxygen-recipes-")));
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (shouldStripBundle && key === "bundle")
+            continue;
+        output[key] = stripWorkflowBundles(entry);
+    }
+    return output;
+}
+function normalizeWorkflowRunErrors(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => normalizeWorkflowRunErrors(entry));
+    if (!isRecord(value))
+        return value;
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        output[key] = normalizeWorkflowRunErrors(entry);
+    }
+    if (output.status === "failed" && (output.error === null || output.error === undefined) && output.lastError !== null && output.lastError !== undefined) {
+        output.error = output.lastError;
+    }
+    if ((output.error === null || output.error === undefined) && isRecord(output.run) && output.run.error !== undefined) {
+        output.error = output.run.error;
+    }
+    return output;
+}
+function isTerminalWorkflowRunStatus(status) {
+    // Terminal here means "stop polling", not "the run is over".
+    //
+    // 'awaiting_approval' pauses the run indefinitely for a human decision (lease
+    // cleared, excluded from claim + lease sweep), so it must stop the tail and
+    // surface the approval rather than poll forever.
+    //
+    // 'waiting' is the same shape with a clock instead of a human: the run is
+    // parked until `ready_at` — typically a provider's own quota reset, which can
+    // be ~20 hours out. Polling that is pointless; the tail stops and reports the
+    // resume time (see readWorkflowRunPauseReason).
+    return status === "completed" || status === "failed" || status === "canceled"
+        || status === "awaiting_approval" || status === "waiting";
+}
+function workflowWebhookDeliveriesPath(options) {
+    const params = new URLSearchParams();
+    const triggerId = readOption(options.triggerId);
+    const workflowId = readOption(options.workflowId);
+    const outcome = readOption(options.outcome);
+    const limit = readPositiveInt(options.limit);
+    if (triggerId)
+        params.set("trigger_id", triggerId);
+    if (workflowId)
+        params.set("workflow_id", workflowId);
+    if (outcome)
+        params.set("outcome", outcome);
+    if (limit)
+        params.set("limit", String(limit));
+    const query = params.toString();
+    return `/api/cli/workflows/webhooks/deliveries${query ? `?${query}` : ""}`;
+}
+export function registerWorkflowsFamily(program, handleAsyncAction) {
+    const workflowRunReadbackHelp = `
+Stored run values:
+  oxygen workflows runs --run-id <run_id> --projection value --path /runs/0/output --json
+  Canonical graph output is a steps map keyed by node id.
+  Read the observed cost receipt with oxygen workflows run <run_id> --json.
+  For large values, follow next_value_cursor with --value-cursor and the same selection.
+  Append value_json fragments in offset order until next_value_cursor is null, then parse the combined JSON.
+`;
+    program
+        .command("workflows")
+        .description("Durable workflow automation commands.")
+        .addHelpText("after", `
+Authoring guide:
+  Install or refresh the focused product skill:
+  oxygen skills install --skill oxygen-workflow-authoring
+
+Web creation chooser:
+  Open /workspaces/<workspace-id>/workflows and click Create workflow.
+  Choose Blank workflow, Workflow template (one workflow), Blueprint
+  (a multi-resource motion), or Import definition. The chooser opens on the
+  collection page; it has no separate public URL.
+  Guide: https://oxygen-agent.com/docs/execution/workflows
+
+Fastest editable graph:
+  1. oxygen workflows events list --search "<outcome>" --kind builtin --json
+  2. oxygen workflows init --id my-workflow
+  3. oxygen workflows schema --subject graph --json
+  4. oxygen workflows lint --file my-workflow.workflow.json --phase draft --json
+  5. oxygen workflows apply --file my-workflow.workflow.json --draft --json
+  6. oxygen workflows lint --file my-workflow.workflow.json --phase publish --json
+
+Draft apply saves an inert editable revision: it costs 0 credits, calls no graph
+nodes, creates no run, and publishes nothing. After publish lint is clean, apply
+without --draft publishes the revision; calling or enabling it remains a separate
+execution/authorization step.
+
+Run completion:
+  Calls without --preview enqueue asynchronously. Use the returned data.run.id as <run_id>:
+  oxygen workflows tail <run_id>
+  Preview calls return data.preview and create no run.
+${workflowRunReadbackHelp}
+`)
+        .addCommand(new Command("templates")
+        .description("Deprecated aliases for `oxygen blueprints` — these route through the canonical blueprint surface (built-in seed templates plus this workspace's saved blueprints).")
+        .addCommand(addCompactListReadFlags(new Command("search")
+        .description("Deprecated alias for `oxygen blueprints list`. Searches Oxygen blueprints (seed templates plus saved blueprints).")
+        .argument("[query]", "Search text.")
+        .option("--tag <tag>", "Filter by blueprint tag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (query, options, command) => {
+        await handleAsyncAction("workflows templates search", options, () => {
+            const params = new URLSearchParams();
+            params.set("query", query ?? "");
+            if (readOption(options.tag))
+                params.set("tag", readOption(options.tag) ?? "");
+            appendCompactListReadQuery(params, command, "blueprints");
+            return requestOxygen(`/api/cli/blueprints?${params.toString()}`);
+        });
+    }), "blueprints"))
+        .addCommand(new Command("describe")
+        .description("Deprecated alias for `oxygen blueprints describe`.")
+        .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (templateId, options) => {
+        await handleAsyncAction("workflows templates describe", options, () => requestOxygen("/api/cli/blueprints/get", {
+            method: "POST",
+            body: { slug: templateId },
+        }));
+    }))
+        .addCommand(new Command("preflight")
+        .description("Deprecated alias for `oxygen blueprints preflight`. Validates inputs and previews effects without running.")
+        .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
+        .requiredOption("--input-json <json>", "Blueprint input as a JSON object.")
+        .option("--mode <mode>", "Deprecated and ignored: blueprints validate without a run mode.")
+        .option("--max-credits <credits>", "Credit ceiling; folded into inputs.max_credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (templateId, options) => {
+        await handleAsyncAction("workflows templates preflight", options, () => requestOxygen("/api/cli/blueprints/preflight", {
+            method: "POST",
+            body: workflowTemplateBlueprintBody(templateId, options),
+        }));
+    }))
+        .addCommand(new Command("apply")
+        .description("Deprecated alias for `oxygen blueprints apply`. Creates a disabled workflow (plus its tables, columns, and prompts) from a blueprint.")
+        .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
+        .requiredOption("--input-json <json>", "Blueprint input as a JSON object.")
+        .option("--workflow-id <workflow_id>", "Select an existing workflow by database UUID or manifest id/slug; an unmatched value creates a separate workflow.")
+        .option("--workflow-name <workflow_name>", "Override the resulting workflow name.")
+        .option("--mode <mode>", "Deprecated and ignored: the workflow is created disabled.")
+        .option("--max-credits <credits>", "Credit ceiling; folded into inputs.max_credits.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (templateId, options) => {
+        await handleAsyncAction("workflows templates apply", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/blueprints/apply", {
+            method: "POST",
+            body: workflowTemplateBlueprintBody(templateId, options, true),
+        }), options));
+    }))
+        .addCommand(new Command("run")
+        .description("Removed: returns a typed 410 deprecation. Use `oxygen blueprints apply <slug>` then `oxygen workflows call <workflow>`.")
+        .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
+        .requiredOption("--input-json <json>", "Blueprint input as a JSON object.")
+        .requiredOption("--mode <mode>", "Execution mode: smoke_test, dry_run, or live.")
+        .option("--workflow-id <workflow_id>", "Workflow id to create or update.")
+        .option("--workflow-name <workflow_name>", "Workflow display name.")
+        .option("--max-credits <credits>", "Required credit ceiling for paid live work.")
+        .option("--approved", "Required for live template runs with side effects.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (templateId, options) => {
+        await handleAsyncAction("workflows templates run", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/templates/run", {
+            method: "POST",
+            body: workflowTemplateActionBody(templateId, options),
+        }), options));
+    })))
+        .addCommand(new Command("schema")
+        .description("Print workflow JSON schemas.")
+        .option("--subject <subject>", "Schema subject: all, apply, call, event, trigger, manifest, graph, or definition.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows schema", options, () => requestOxygen(`/api/cli/workflows/schema?subject=${encodeURIComponent(options.subject ?? "all")}`));
+    }))
+        .addCommand(new Command("init")
+        .description("Create a local editable workflow graph. Use --format recipe only for the legacy durable-recipe authoring path.")
+        .option("--dir <path>", "Directory to scaffold into. Defaults to the current directory.")
+        .option("--id <id>", "Workflow id. Defaults to 'my-workflow' (or 'my-recipe' with --format recipe).")
+        .option("--name <name>", "Workflow display name. Defaults to 'My workflow' (or 'My recipe' with --format recipe).")
+        .addOption(new Option("--format <format>", "Authoring format: graph (default) or legacy recipe.").choices(["graph", "recipe"]).default("graph"))
+        .option("--force", "Overwrite existing files instead of skipping them.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows init", options, async () => scaffoldWorkflowProject(options));
+    }))
+        .addCommand(new Command("lint")
+        .description("Compile and validate an authored workflow file against the same draft/publish readiness contract as the web editor and apply. Saves nothing, runs nothing, calls no provider, and spends no credits. Portable exports use `workflows import --preflight` because their destination connection bindings are part of validation.")
+        .requiredOption("--file <path>", "Workflow module or manifest JSON file.")
+        .addOption(new Option("--phase <phase>", "Validation phase: publish (default) or draft.").choices(["draft", "publish"]).default("publish"))
+        .option("--approved", "Validate that revision-bound autonomous authority is present; grants nothing because lint is read-only.")
+        .option("--max-credits <n>", "Candidate positive per-delivery ceiling; omit to validate the plan default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows lint", options, async () => {
+            const manifest = await compileWorkflowFile(options.file);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return requestOxygen("/api/cli/workflows/lint", {
+                method: "POST",
+                body: {
+                    manifest,
+                    phase: options.phase ?? "publish",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("apply")
+        .description("Compile and save a workflow definition; --draft appends an editable revision without publishing it. Apply costs 0 credits, calls no graph nodes, creates no run, and preserves disabled status; call or enable separately to execute.")
+        .requiredOption("--file <path>", "Workflow module or manifest JSON file.")
+        .option("--approved", "Authorize autonomous tool calls for this revision.")
+        .option("--max-credits <n>", "Optional explicit positive ceiling for each autonomous delivery; omit to use the plan-tier default.")
+        .option("--draft", "Save without going live: keeps the running version serving every trigger. Publish later by applying again without --draft.")
+        .option("--review", "Show what publishing this would change against the version now serving triggers — added, removed and modified steps, what leaves Oxygen, the accounts used, and whether it needs standing authority. Writes nothing.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows apply", options, async () => {
+            const manifest = await compileWorkflowFile(options.file);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            const data = prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/apply", {
+                method: "POST",
+                body: {
+                    manifest,
+                    // Sent only when drafting. Omitting it entirely keeps the request
+                    // byte-identical to what every previous CLI sent, so behaviour
+                    // against an older server is unchanged rather than merely equivalent.
+                    ...(options.draft ? { publish: false } : {}),
+                    ...(options.review ? { review: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            }), options);
+            writeScheduleWarnings(data);
+            if (!options.json)
+                writeWorkflowPlanLimitNotices(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("export")
+        .description("Export one graph-native workflow as a portable, editable definition with source account ids and trigger authority removed.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .option("--out <path>", "Write only the portable definition JSON to this path.")
+        .option("--force", "Overwrite --out if it already exists.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows export", options, async () => {
+            const data = await requestOxygen("/api/cli/workflows/export", { method: "POST", body: { workflow } });
+            const outPath = readOption(options.out);
+            if (!outPath)
+                return data;
+            const absolutePath = resolve(outPath);
+            if (existsSync(absolutePath) && !options.force) {
+                throw new OxygenError("workflow_export_file_exists", `Refusing to overwrite '${absolutePath}'. Pass --force to replace it.`, { details: { path: absolutePath }, exitCode: 1 });
+            }
+            writeFileSync(absolutePath, `${JSON.stringify(data.definition, null, 2)}\n`, "utf8");
+            return { ...data, written_to: absolutePath };
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Preflight or install a portable workflow definition. Imports are create-only and always disabled.")
+        .requiredOption("--file <path>", "Portable .oxygen-workflow.json file from workflows export.")
+        .option("--preflight", "Validate destination accounts and collisions without creating anything.")
+        .option("--workflow-id <id>", "Override the destination workflow id.")
+        .option("--workflow-name <name>", "Override the destination workflow name.")
+        .option("--webhook-trigger-id <id>", "Override the regenerated destination webhook trigger id.")
+        .option("--connection <binding_id=connection_id>", "Bind one exported account requirement to an active destination connection (repeatable).", collectMultiple, [])
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction(options.preflight ? "workflows import preflight" : "workflows import", options, async () => {
+            const definition = readPortableWorkflowDefinitionFile(options.file);
+            const connectionBindings = parseWorkflowConnectionBindings(options.connection ?? []);
+            return requestOxygen(options.preflight
+                ? "/api/cli/workflows/import/preflight"
+                : "/api/cli/workflows/import", {
+                method: "POST",
+                body: {
+                    definition,
+                    connection_bindings: connectionBindings,
+                    ...(readOption(options.workflowId) ? { workflow_id: readOption(options.workflowId) } : {}),
+                    ...(readOption(options.workflowName) ? { workflow_name: readOption(options.workflowName) } : {}),
+                    ...(readOption(options.webhookTriggerId)
+                        ? { webhook_trigger_id: readOption(options.webhookTriggerId) }
+                        : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List workflow automations.")
+        .addOption(new Option("--include-archived", "Deprecated no-op retained for compatibility.").hideHelp())
+        .option("--tag <tag>", "Only workflows carrying this workspace tag (see `oxygen tags list`).")
+        .option("--node-testable", "Only canonical graph workflows, the ones `workflows call --node` can scope a test to. Legacy recipes and v1 step lists own their own execution order and are excluded.")
+        .option("--search <text>", "Match on name, slug, trigger event, or an integration the workflow uses — so \"meeting\" or \"hubspot\" finds it without knowing what someone named it.")
+        .option("--limit <n>", "Maximum workflows to list. Defaults to 200; hard cap is 1000.")
+        .option("--all", "List every workflow instead of the most-recently-updated window.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nEach row carries `format` (graph, recipe or steps) and `nodeTestable`, so you can tell which workflows support single-step testing without opening them.\nLists the 200 most recently updated workflows by default; `capped` in the JSON envelope says when there are more.\n")
+        .action(async (options) => {
+        await handleAsyncAction("workflows list", options, async () => {
+            const params = new URLSearchParams();
+            const tag = readOption(options.tag);
+            if (tag)
+                params.set("tag", tag);
+            if (options.nodeTestable)
+                params.set("node_testable", "true");
+            const search = readOption(options.search);
+            if (search)
+                params.set("search", search);
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            if (options.all)
+                params.set("all", "true");
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/workflows${qs}`);
+            if (!options.json) {
+                writeDisabledWorkflowNotices(data);
+                writeListCapNotice(data, "workflow(s)");
+            }
+            return data;
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one workflow automation, including any cron slowdown to your plan's minimum interval and `draftRevision` when a saved revision is newer than the published one. The top-level `status` is the live state; `manifest.workflow.status` is what the revision was authored with and does not change on enable or disable.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows get", options, async () => {
+            const data = await requestOxygen("/api/cli/workflows/get", {
+                method: "POST",
+                readOnly: true,
+                body: { workflow },
+            });
+            if (!options.json) {
+                writeDisabledWorkflowNotices(data);
+                writeWorkflowPlanLimitNotices(data);
+            }
+            return prepareWorkflowCliOutput(data, options);
+        });
+    }))
+        .addCommand(new Command("tag")
+        .description("Replace a workflow's workspace tags (Tags primitive; \"\" clears). Tags link the workflow to sequences, tables, and wiki pages carrying the same tag — browse with `oxygen tags get <tag>`. Org metadata only: no new revision is cut.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .requiredOption("--tags <csv>", "Comma-separated tags; \"\" clears them.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows tag", options, () => requestOxygen("/api/cli/workflows/tags", {
+            method: "POST",
+            body: { workflow, tags: readCsvOption(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("duplicate")
+        .description("Duplicate a workflow automation as a disabled copy by default.")
+        .argument("<workflow>", "Source workflow id, slug, or name.")
+        .option("--name <name>", "Display name for the duplicated workflow. Defaults to '<source> Copy'.")
+        .option("--workflow-id <workflow_id>", "Workflow id for the duplicated workflow. Defaults to a unique '<source>-copy' id.")
+        .option("--trigger-id <trigger_id>", "Webhook trigger id for duplicated webhook workflows.")
+        .option("--status <status>", "active or disabled. Defaults to disabled.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows duplicate", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/duplicate", {
+            method: "POST",
+            body: {
+                workflow,
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.workflowId) ? { new_workflow_id: readOption(options.workflowId) } : {}),
+                ...(readOption(options.triggerId) ? { trigger_id: readOption(options.triggerId) } : {}),
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+            },
+        }), options));
+    }))
+        .addCommand(new Command("call")
+        .description("Run a workflow — or preview it first. `--preview` returns data.preview without creating a run: it shows every step that leaves Oxygen, the accounts it would use, and what one run costs. Calls without --preview enqueue asynchronously without simulating the trigger; use the returned data.run.id as <run_id> in `oxygen workflows tail <run_id>`.")
+        .argument("[workflow]", "Workflow id, slug, or name.")
+        .option("--workflow <workflow>", "Workflow id, slug, or name.")
+        .option("--workflow-id <workflow_id>", "Workflow id or slug.")
+        .option("--workflow-name <workflow_name>", "Workflow name.")
+        .option("--input-json <json>", "Workflow input object in every mode, including smoke-test. Defaults to {}.")
+        .option("--mode <mode>", "Execution mode. smoke-test/dry-run: 0 credits, no paid provider calls or external writes; internal reads still execute. live: may spend/write and requires approval + cap. Not needed with --preview, which runs nothing.")
+        .option("--idempotency-key <key>", "Optional idempotency key.")
+        .option("--max-credits <n>", "Required credit ceiling for live calls.")
+        .option("--approved", "Required for live calls after inspecting a dry run.")
+        .option("--revision <n>", "Run a specific saved version instead of the live one. Dry-run and smoke-test only: publish a version to run it live.")
+        .addOption(new Option("--test-scope <workflow|node>", "Create a durable non-live whole-workflow or node test; node requires --node.").choices(["workflow", "node"]))
+        .option("--node <node_id>", "Test one node: runs that node plus only the predecessors it needs, from the same saved graph. Dry-run and smoke-test only.")
+        .option("--preview", "Show what a live run of this exact version would do — every step that leaves Oxygen, the accounts it would use, and the minimum number of billable steps and credits it would cost — without running anything. AI and enrichment steps bill per row and can cost more than that floor. Needs no --mode: it always describes a live run.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nSafety: smoke_test and dry_run share one boundary: 0 credits, no paid provider calls, no external writes. Oxygen internal reads use current workspace data, and oxygen.http_json_request may make a real outbound GET. Every execution mode creates an inspectable Workflow run record; --preview creates none.\n\n--node scopes a test to one step. Oxygen plans the slice on the server from the exact saved version and records it on the run, so the run shows precisely which nodes were allowed to execute; you never submit a node list. Selecting the trigger, a disabled node, or a node unreachable from the trigger is refused with the reason. Only canonical graph workflows support it.\n")
+        .addHelpText("after", workflowRunReadbackHelp)
+        .action(async (workflowArg, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        const revisionVersion = readPositiveNumber(options.revision);
+        await handleAsyncAction("workflows call", options, async () => {
+            // --mode stopped being a commander requiredOption so that --preview,
+            // which executes nothing, no longer forces the caller to pick a mode
+            // the server then discards. A real call still needs one. Thrown
+            // INSIDE handleAsyncAction so it prints the CLI's error envelope and
+            // exits 2 like any other usage error — thrown outside, it escaped as
+            // an unhandled rejection and showed the user a Node stack trace.
+            if (!options.preview && !readOption(options.mode)) {
+                throw new OxygenError("invalid_request", "--mode is required. Use smoke-test, dry-run, or live. To see what a live run would do without running it, use --preview — it runs nothing and needs no mode.", { exitCode: 2 });
+            }
+            const idempotencyKey = readOption(options.idempotencyKey);
+            return prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/call", {
+                method: "POST",
+                ...(options.preview ? { previewOnly: true } : {}),
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                body: {
+                    workflow: readOption(workflowArg) ?? readOption(options.workflow),
+                    ...(readOption(options.workflowId) ? { workflow_id: readOption(options.workflowId) } : {}),
+                    ...(readOption(options.workflowName) ? { workflow_name: readOption(options.workflowName) } : {}),
+                    input: options.inputJson ? parseJsonObject(options.inputJson) : {},
+                    ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(revisionVersion !== undefined ? { revision_version: revisionVersion } : {}),
+                    ...(readOption(options.testScope) ? { test_scope: readOption(options.testScope) } : {}),
+                    ...(readOption(options.node) ? { test_node_id: readOption(options.node) } : {}),
+                    ...(options.preview ? { preview: true } : {}),
+                },
+            }), options);
+        });
+    }))
+        .addCommand(new Command("webhooks")
+        .description("Workflow webhook trigger utilities. A trigger's inbound URL and the deliveries a minute it accepts (`rate_limit`) are in `oxygen workflows get <workflow>`. Senders authenticate by sending the trigger's shared secret in the `x-oxygen-workflow-secret` header; a missing or wrong secret is recorded as a `rejected` delivery that starts no run and costs nothing.")
+        .addCommand(new Command("rotate")
+        .description("Replace a workflow webhook's shared secret. Previews by default; the old sender secret stops working immediately after approval.")
+        .argument("<workflow>", "Webhook workflow id, slug, or name.")
+        .option("--approved", "Confirm replacement after reviewing the preview. The new secret is shown once.")
+        .option("--json", "Print a JSON envelope.")
+        .action((workflow, options) => handleAsyncAction("workflows webhooks rotate", options, () => requestOxygen("/api/cli/workflows/webhooks/rotate", {
+        method: "POST",
+        previewOnly: !options.approved,
+        body: {
+            workflow,
+            ...(options.approved ? { approved: true } : {}),
+        },
+    }))))
+        .addCommand(new Command("replay")
+        .description("Create a durable, inspectable run in dry_run mode from one verified outcome=ran delivery's exact original revision and payload. Never resends the webhook or adds an inbound delivery-history row; uses 0 credits, no paid provider calls, and no external writes. Internal reads and outbound HTTP GETs can still execute.")
+        .argument("<delivery_id>", "Verified outcome=ran delivery UUID from `oxygen workflows webhooks deliveries`.")
+        .option("--request-key <key>", "Idempotency key. Reusing the same delivery/key returns the existing replay run; it never creates a second run.")
+        .option("--json", "Print a JSON envelope.")
+        .action((deliveryId, options) => handleAsyncAction("workflows webhooks replay", options, () => requestOxygen("/api/cli/workflows/webhooks/deliveries/replay", {
+        method: "POST",
+        body: {
+            delivery_id: deliveryId,
+            request_key: readOption(options.requestKey) ?? randomUUID(),
+        },
+    }))))
+        .addCommand(new Command("deliveries")
+        .description("List inbound workflow webhook deliveries: what arrived, whether it verified, and the run it started. Stored headers never include `x-oxygen-workflow-secret`, so its absence does not show whether a rejected sender's secret was missing or wrong. Replays never append here; only a verified outcome=ran delivery can be replayed.")
+        .argument("[trigger_id]", "Optional webhook trigger name, such as lead-created.")
+        .option("--workflow-id <id>", "Filter to this workflow's deliveries, including rejected and blocked ones that started no run.")
+        .option("--outcome <outcome>", "Filter by rejected (sender authentication failed), blocked (authenticated, no run), or ran.")
+        .option("--limit <n>", "Maximum deliveries to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action((triggerId, options) => handleAsyncAction("workflows webhooks deliveries", options, () => requestOxygen(workflowWebhookDeliveriesPath({
+        triggerId,
+        workflowId: options.workflowId,
+        outcome: options.outcome,
+        limit: options.limit,
+    }))))))
+        .addCommand(new Command("revisions")
+        .description("Saved revision history for one workflow, newest first — includes unpublished drafts and published versions; use --include-manifest to inspect either.")
+        .argument("[workflow]", "Workflow id, slug, or name.")
+        .option("--workflow <workflow>", "Workflow id, slug, or name.")
+        .option("--limit <n>", "Maximum revisions to return. Defaults to 50.")
+        .option("--include-manifest", "Include each revision's full manifest.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflowArg, options) => {
+        await handleAsyncAction("workflows revisions", options, () => {
+            const workflow = readOption(workflowArg) ?? readOption(options.workflow);
+            const query = new URLSearchParams();
+            if (workflow)
+                query.set("workflow", workflow);
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                query.set("limit", String(limit));
+            if (options.includeManifest)
+                query.set("include_manifest", "true");
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/workflows/revisions${suffix}`);
+        });
+    })
+        .addCommand(new Command("restore")
+        .description("Re-publish an earlier version as the newest one. Append-only: restoring v3 applies v3's manifest as v9 rather than rewinding, so the restore is itself undoable and history stays a record of what happened. It clears the same gates a fresh apply does — lint, tool effects, cron cadence — so an autonomous tool-bearing workflow needs --approved (and a per-delivery --max-credits, or the plan default) to arm again.")
+        .argument("[workflow]", "Workflow id, slug, or name.")
+        .requiredOption("--version <n>", "The revision version to re-publish (see `oxygen workflows revisions`).")
+        .option("--workflow <workflow>", "Workflow id, slug, or name.")
+        .option("--approved", "Required to re-arm an autonomous tool-bearing workflow.")
+        .option("--max-credits <n>", "Per-delivery credit ceiling for the restored revision. Omit to bind the plan-tier default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflowArg, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        await handleAsyncAction("workflows revisions restore", options, () => requestOxygen("/api/cli/workflows/revisions/restore", {
+            method: "POST",
+            body: {
+                workflow: readOption(workflowArg) ?? readOption(options.workflow),
+                version: Number(readOption(options.version)),
+                ...(options.approved ? { approved: true } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+            },
+        }));
+    })))
+        .addCommand(new Command("events")
+        .description("Workflow event trigger utilities.")
+        .addCommand(new Command("list")
+        .description("Search and filter every registered app-native and connected event this workspace can use as a workflow trigger, including setup-required events.")
+        .option("--search <text>", "Match labels, catalog ids, descriptions, endpoints, filters, or payload fields.")
+        .option("--source <source>", "Match one event source exactly, such as sequencer or crm.")
+        .option("--kind <kind>", "Match builtin, integration, or existing events.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", `
+Cost: 0 credits · read-only.
+
+Use each returned source, event, and filters array together. Curated presets can
+share one underlying source/event pair and differ only by filters.
+
+This is the trigger-ready workspace catalog. oxygen integrations events list
+instead shows raw provider webhook definitions and the subscriptions that feed
+connected entries into this catalog.
+
+Kinds:
+  builtin      Curated Oxygen preset with labels, filters, and payload fields.
+  integration  Event from an active workspace integration subscription.
+  existing     Raw source/event retained from an existing workflow trigger;
+               no preset filter is required.
+
+Readiness:
+  Events that need setup remain selectable and draft-saveable. Their readiness
+  reason and exact setup action are returned here; publish/enable stays blocked
+  until the prerequisite is ready.
+
+Example trigger:
+  {"type":"event","source":"crm","event":"activity_created",
+   "filters":[{"path":"activity_type","op":"eq","value":"meeting_booked"}]}
+
+Full trigger schema: oxygen workflows schema --subject trigger --json
+`)
+        .action(async (options) => {
+        try {
+            const query = new URLSearchParams();
+            const search = readOption(options.search);
+            const source = readOption(options.source);
+            const kind = readOption(options.kind);
+            if (search)
+                query.set("search", search);
+            if (source)
+                query.set("source", source);
+            if (kind)
+                query.set("kind", kind);
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/workflows/events/catalog${suffix}`);
+            if (options.json)
+                writeJson(success("workflows events list", data));
+            else
+                process.stdout.write(formatWorkspaceEventsList(data));
+        }
+        catch (error) {
+            emitCliFailure("workflows events list", error);
+        }
+    }))
+        .addCommand(new Command("get")
+        .description("Get one curated workspace-event preset and its ready-to-copy trigger object.")
+        .argument("<catalog_id>", "Exact catalog id returned by workflows events list.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nCost: 0 credits · read-only. Integration/existing entries have no curated catalog id; filter them with workflows events list.\n")
+        .action(async (catalogId, options) => {
+        try {
+            const data = await requestOxygen(`/api/cli/workflows/events/catalog?catalog_id=${encodeURIComponent(catalogId)}`);
+            if (options.json)
+                writeJson(success("workflows events get", data));
+            else
+                process.stdout.write(formatWorkspaceEventDetail(data));
+        }
+        catch (error) {
+            emitCliFailure("workflows events get", error);
+        }
+    }))
+        .addCommand(new Command("emit")
+        .description("Emit a normalized workflow event and enqueue matching event-triggered workflows.")
+        .requiredOption("--source <source>", "Event source, such as instantly, calendar, hubspot, or oxygen.notetaker.")
+        .requiredOption("--event <event>", "Event type, such as email.reply_received.")
+        .requiredOption("--payload-json <json>", "Normalized event payload object.")
+        .option("--raw-payload-json <json>", "Optional raw provider payload object.")
+        .option("--headers-json <json>", "Optional delivery headers object.")
+        .option("--external-event-id <id>", "Provider event id for idempotency and inspection.")
+        .option("--idempotency-key <key>", "Optional explicit event idempotency key.")
+        .requiredOption("--mode <mode>", "Execution mode: live, dry-run (dry_run), or smoke-test (smoke_test).")
+        .option("--max-credits <n>", "Required per-delivery credit ceiling for live event emission.")
+        .option("--approved", "Required for live event emission after inspecting a dry run.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows events emit", options, async () => {
+            const rawPayloadJson = readOption(options.rawPayloadJson);
+            const headersJson = readOption(options.headersJson);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/events/emit", {
+                method: "POST",
+                body: {
+                    source: readOption(options.source),
+                    event: readOption(options.event),
+                    payload: parseJsonObject(options.payloadJson),
+                    ...(rawPayloadJson ? { raw_payload: parseJsonObject(rawPayloadJson) } : {}),
+                    ...(headersJson ? { headers: parseJsonObject(headersJson) } : {}),
+                    ...(readOption(options.externalEventId) ? { external_event_id: readOption(options.externalEventId) } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                    ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            }), options);
+        });
+    })))
+        .addCommand(addContractFlags(new Command("runs")
+        .description("List stored workflow runs. Optional windows preserve complete public values without executing a workflow."), WORKFLOW_RUN_LIST_CONTRACT, WORKFLOW_RUN_LIST_FLAG_OVERLAY)
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nFor complete bounded history use --projection summary/full; echo nextCursor with the same filters. Unqualified legacy reads issue a continuation only with an explicit --limit. Value windows require --run-id and reauthorize the exact filtered public row.\n")
+        .action(async (options) => {
+        await handleAsyncAction("workflows runs", options, async () => {
+            const args = readWorkflowRunListFlags(options);
+            const query = workflowRunListQueryParams(args);
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/workflows/runs${suffix}`);
+            // Opt-in windows are lossless public native receipts. Legacy bundle
+            // stripping/error aliases still apply only to the unqualified read.
+            return ["projection", "path", "value_cursor", "max_chars"].some(key => args[key] !== undefined)
+                ? data : prepareWorkflowCliOutput(data, options);
+        });
+    }))
+        .addCommand(new Command("failures")
+        .description("List failed workflow runs and trigger scheduler failures.")
+        .option("--limit <n>", "Maximum failures per group. Defaults to 25; server cap is 100.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows failures", options, async () => {
+            const query = new URLSearchParams();
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                query.set("limit", String(limit));
+            if (options.includeBundle)
+                query.set("include_bundle", "true");
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return prepareWorkflowCliOutput(await requestOxygen(`/api/cli/workflows/failures${suffix}`), options);
+        });
+    }))
+        .addCommand(new Command("run")
+        .description("Read one workflow run, including waiting and awaiting_approval pause state. This command changes nothing.")
+        .argument("<run_id>", "Workflow run UUID returned as data.run.id by workflows call/tail; not the separate provenance run id.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nWebhook replay: for a webhook-origin run, find its verified delivery with `oxygen workflows webhooks deliveries --workflow-id <workflow-uuid> --outcome ran`, then use `oxygen workflows webhooks replay <delivery-id>`. The replay response and run metadata retain the source delivery/run lineage.\n")
+        .action(async (runId, options) => {
+        await handleAsyncAction("workflows run", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/run", {
+            method: "POST",
+            readOnly: true,
+            body: { run_id: runId },
+        }), options));
+    }))
+        .addCommand(new Command("retry")
+        .description("Preview retrying a failed run from its first failed step. Completed steps stay preserved; ambiguous external writes are refused.")
+        .argument("<run_id>", "Failed workflow run UUID.")
+        .option("--approved", "Execute the reviewed retry plan. Without this flag, returns a read-only preview.")
+        .option("--max-credits <n>", "Required new positive credit ceiling when retrying a live run.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("workflows retry", options, async () => {
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/retry", {
+                method: "POST",
+                previewOnly: !options.approved,
+                body: {
+                    run_id: runId,
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            }), options);
+        });
+    }))
+        .addCommand(new Command("tail")
+        .description("Poll until a workflow finishes or parks in waiting/awaiting_approval; clock waits resume automatically.")
+        .argument("<run_id>", "Workflow run UUID returned as data.run.id by workflows call; distinct from data.run.runId.")
+        .option("--timeout-seconds <n>", "Maximum time to wait. Defaults to 600.")
+        .option("--interval-seconds <n>", "Polling interval. Defaults to 2.")
+        .option("--include-bundle", "Include durable recipe bundles in JSON output.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", workflowRunReadbackHelp)
+        .action(async (runId, options) => {
+        await handleAsyncAction("workflows tail", options, async () => prepareWorkflowCliOutput(await waitForWorkflowRun(runId, options), options));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel a queued or running workflow run.")
+        .argument("<run_id>", "Workflow run UUID.")
+        .option("--preview", "Show what cancelling would and would not undo — steps in flight, and any external write already dispatched that cancelling cannot recall. Cancels nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nCancelling stops further steps; it cannot recall a step already dispatched to a provider. Use --preview first when the run may be mid-write.\n")
+        .action(async (runId, options) => {
+        await handleAsyncAction("workflows cancel", options, () => requestOxygen("/api/cli/workflows/cancel", {
+            method: "POST",
+            ...(options.preview ? { previewOnly: true } : {}),
+            body: {
+                run_id: runId,
+                ...(options.preview ? { preview: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("approvals")
+        .description("List workflow runs awaiting a human approval decision (the mid-run approval inbox).")
+        .option("--status <status>", "Filter: pending (default), approved, rejected, expired, or all.")
+        .option("--run-id <run_id>", "Only approvals for this workflow run.")
+        .option("--limit <n>", "Maximum approvals to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows approvals", options, () => {
+            const query = new URLSearchParams();
+            if (readOption(options.status))
+                query.set("status", readOption(options.status) ?? "");
+            if (readOption(options.runId))
+                query.set("run_id", readOption(options.runId) ?? "");
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                query.set("limit", String(limit));
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/workflows/approvals${suffix}`);
+        });
+    }))
+        .addCommand(new Command("resume")
+        .description("Approve or reject a paused mid-run workflow approval, resuming the run.")
+        .argument("<run_id>", "Workflow run UUID.")
+        .requiredOption("--decision <decision>", "approve or reject.")
+        .option("--step-id <step_id>", "Approval step id, when a run has more than one pending gate.")
+        .option("--plan-hash <plan_hash>", "Reviewed plan hash; the decision is refused if the plan changed since review.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("workflows resume", options, () => requestOxygen("/api/cli/workflows/resume", {
+            method: "POST",
+            body: {
+                run_id: runId,
+                decision: readOption(options.decision),
+                ...(readOption(options.stepId) ? { step_id: readOption(options.stepId) } : {}),
+                ...(readOption(options.planHash) ? { plan_hash: readOption(options.planHash) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("enable")
+        .description("Enable one or more workflow automations and their current triggers. Prints the schedule's projected automation-action burn; refuses a cron cadence the plan's monthly allowance cannot sustain. Pass several workflows to enable them in one bulk call.")
+        .argument("<workflows...>", "One or more workflow ids, slugs, or names.")
+        .option("--reason <text>", "Why you are enabling it. Recorded on the workflow and shown to the workspace.")
+        .option("--approved", "Authorize autonomous tool calls for each current revision.")
+        .option("--max-credits <n>", "Optional explicit positive ceiling for each autonomous delivery; omit to use the plan-tier default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflows, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        if (workflows.length === 1) {
+            await handleAsyncAction("workflows enable", options, async () => {
+                const data = await requestOxygen("/api/cli/workflows/enable", {
+                    method: "POST",
+                    body: {
+                        workflow: workflows[0],
+                        ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                        ...(options.approved ? { approved: true } : {}),
+                        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                    },
+                });
+                writeAutomationProjection(data);
+                writeScheduleWarnings(data);
+                return data;
+            });
+            return;
+        }
+        try {
+            const data = await requestOxygen("/api/cli/workflows/enable", {
+                method: "POST",
+                body: {
+                    workflows,
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            });
+            if (options.json) {
+                writeJson(success("workflows enable", data));
+            }
+            else {
+                writeBulkWorkflowResults(data, "enabled");
+            }
+            writeScheduleWarnings(data);
+        }
+        catch (error) {
+            emitCliFailure("workflows enable", error);
+        }
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable one or more workflow automations and their current triggers. Records who disabled it, from where, and why — the workspace sees it on the workflow. Pass several workflows to disable them in one bulk call.")
+        .argument("<workflows...>", "One or more workflow ids, slugs, or names.")
+        .option("--reason <text>", "Why you are disabling it. Recorded on the workflow and shown to the workspace.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflows, options) => {
+        if (workflows.length === 1) {
+            await handleAsyncAction("workflows disable", options, () => requestOxygen("/api/cli/workflows/disable", {
+                method: "POST",
+                body: {
+                    workflow: workflows[0],
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            }));
+            return;
+        }
+        try {
+            const data = await requestOxygen("/api/cli/workflows/disable", {
+                method: "POST",
+                body: {
+                    workflows,
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            });
+            if (options.json) {
+                writeJson(success("workflows disable", data));
+            }
+            else {
+                writeBulkWorkflowResults(data, "disabled");
+            }
+        }
+        catch (error) {
+            emitCliFailure("workflows disable", error);
+        }
+    }))
+        .addCommand(new Command("delete")
+        .description("Preview or permanently delete one or more workflow automations. Deletion disarms the workflow and removes its definition, revisions, triggers, and workflow-scoped budget policies; historical run and usage records remain inspectable. Run without --yes to preview, then repeat with --yes to approve.")
+        .argument("<workflows...>", "One or more workflow ids, slugs, or names.")
+        .addOption(new Option("--purge", "Deprecated no-op retained for compatibility.").hideHelp())
+        .option("--yes", "Approve the previewed permanent deletion.")
+        .option("--reason <text>", "Why you are deleting it. Attached to the deletion request.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflows, options) => {
+        try {
+            const single = workflows.length === 1;
+            const data = await requestOxygen("/api/cli/workflows/delete", {
+                method: "POST",
+                previewOnly: !options.yes,
+                body: {
+                    ...(single ? { workflow: workflows[0] } : { workflows }),
+                    ...(options.yes ? { approved: true } : {}),
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            });
+            if (options.json) {
+                writeJson(success("workflows delete", data));
+                return;
+            }
+            if (single) {
+                const workflow = isRecord(data.workflow) ? data.workflow : null;
+                const slug = workflow && typeof workflow.slug === "string" ? workflow.slug : workflows[0];
+                process.stdout.write(`deleted ${slug}\n`);
+                writeWorkflowActionTail(data);
+            }
+            else {
+                writeBulkWorkflowResults(data, "deleted");
+            }
+        }
+        catch (error) {
+            emitCliFailure("workflows delete", error);
+        }
+    }))
+        .addCommand(new Command("rename")
+        .description("Rename a workflow automation's display name only — its id and slug are unchanged, and the next `workflows apply` from source overwrites the name.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .argument("<name>", "New display name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, name, options) => {
+        try {
+            const data = await requestOxygen("/api/cli/workflows/rename", {
+                method: "POST",
+                body: { workflow, name },
+            });
+            if (options.json) {
+                writeJson(success("workflows rename", data));
+                return;
+            }
+            const renamed = isRecord(data.workflow) ? data.workflow : null;
+            const slug = renamed && typeof renamed.slug === "string" ? renamed.slug : workflow;
+            const displayName = renamed && typeof renamed.name === "string" ? renamed.name : name;
+            process.stdout.write(`renamed ${slug} to "${displayName}"\n`);
+            writeWorkflowActionTail(data);
+        }
+        catch (error) {
+            emitCliFailure("workflows rename", error);
+        }
+    }))
+        .addCommand(new Command("mcp")
+        .description("Expose hosted Workflows as dynamic MCP tools (oxygen_workflow_<slug>). For reusable table Functions, use oxygen functions.")
+        .addCommand(new Command("enable")
+        .description("Publish an active workflow as a callable MCP tool so any MCP client can run it. The published tool appears to MCP clients as oxygen_workflow_<slug>.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .option("--display-name <name>", "Display name for the published MCP tool.")
+        .option("--description <text>", "Description for the published MCP tool.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows mcp enable", options, async () => {
+            const data = await requestOxygen("/api/cli/workflows/mcp", {
+                method: "POST",
+                body: {
+                    workflow,
+                    enabled: true,
+                    ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
+                    ...(readOption(options.description) ? { description: readOption(options.description) } : {}),
+                },
+            });
+            // Surface the resolved MCP tool name. Prefer the server's, fall
+            // back to the canonical builder on the server-resolved slug.
+            const slug = data?.workflow?.slug;
+            const toolName = data?.tool_name
+                ?? (typeof slug === "string" ? workflowMcpToolName(slug) : null);
+            if (toolName) {
+                // MCP tool names are capped at MAX_MCP_TOOL_NAME_LENGTH. Over the
+                // limit the flag is set but the tool is SKIPPED in tools/list until
+                // the slug is shortened — always warn (stderr, JSON stays clean).
+                // Under it, confirm the callable name in human output only (the
+                // JSON envelope already carries tool_name for --json callers).
+                if (toolName.length > MAX_MCP_TOOL_NAME_LENGTH) {
+                    process.stderr.write(`warning: "${toolName}" is ${toolName.length} chars (limit ${MAX_MCP_TOOL_NAME_LENGTH}) — the workflow is enabled for MCP but will not appear in tools/list until its slug is shortened.\n`);
+                }
+                else if (!options.json) {
+                    process.stderr.write(`Published as MCP tool ${toolName} — call it from any MCP client.\n`);
+                }
+            }
+            return data;
+        });
+    }))
+        .addCommand(new Command("disable")
+        .description("Unpublish a workflow's MCP tool. The workflow stays active and callable via `oxygen workflows call`.")
+        .argument("<workflow>", "Workflow id, slug, or name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (workflow, options) => {
+        await handleAsyncAction("workflows mcp disable", options, () => requestOxygen("/api/cli/workflows/mcp", {
+            method: "POST",
+            body: { workflow, enabled: false },
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List workflows currently published as MCP tools.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("workflows mcp list", options, () => requestOxygen("/api/cli/workflows/mcp-callable"));
+    })));
+}