@runcofactor/cli 0.10.0 → 0.15.0

package/dist/{workflow-XYFH5LTP.js → workflow-T4HSAOGW.js}

@@ -4,22 +4,17 @@ import {
 } from "./chunk-4NRDONSC.js";
 import {
   workflowToSpec
-} from "./chunk-B2VISN2V.js";
+} from "./chunk-7VMO2WOZ.js";
 import {
   applyWorkflowTagFlags
-} from "./chunk-XQXVG7RA.js";
+} from "./chunk-FNPMWDUQ.js";
 import {
   alignSnapshotNodeIds
 } from "./chunk-JDBCZ3Z2.js";
 import {
   apiRequest,
   renderWorkflowUserError
-} from "./chunk-WOHL4FTB.js";
-import {
-  NODE_TYPE_LABEL,
-  USER_SETTABLE_WORKFLOW_STATUSES,
-  normalizeNodeType
-} from "./chunk-SJJW77WN.js";
+} from "./chunk-PRBRSIZP.js";
 import {
   apiFetch,
   exitOnFailure,
@@ -30,8 +25,16 @@ import {
   hasFlag,
   resolveAppUrl,
   resolveConfig
-} from "./chunk-A4OFTUVV.js";
+} from "./chunk-3X3NW7QA.js";
+import {
+  specExtension
+} from "./chunk-JMJVGMXI.js";
 import "./chunk-JWHYXEA2.js";
+import {
+  NODE_TYPE_LABEL,
+  USER_SETTABLE_WORKFLOW_STATUSES,
+  normalizeNodeType
+} from "./chunk-JYGNMKZ5.js";
 import "./chunk-VKVL7WBN.js";
 
 // src/workflow.ts
@@ -41,7 +44,6 @@ import process9 from "process";
 // src/workflow-create.ts
 import fs from "fs/promises";
 import process2 from "process";
-import { createParser } from "eventsource-parser";
 async function readFromStdin() {
   const chunks = [];
   const stdin = process2.stdin;
@@ -144,165 +146,6 @@ Available credentials:
 ${lines.join("\n")}`
   );
 }
-async function fetchSuiteLiveState(apiUrl, token, suiteId) {
-  try {
-    const res = await fetch(`${apiUrl}/workflows/test-executions/${suiteId}/live-state`, {
-      headers: { Authorization: `Bearer ${token}` }
-    });
-    if (!res.ok) return null;
-    return await res.json();
-  } catch {
-    return null;
-  }
-}
-async function runAndPublish(opts) {
-  const { apiUrl, token, workflowId, workflowName, timeoutMs } = opts;
-  const body = {};
-  if (opts.propertyId) body.propertyId = opts.propertyId;
-  if (opts.environmentId) body.environmentId = opts.environmentId;
-  const triggerUrl = `${apiUrl}/workflows/test-runs?namePattern=${encodeURIComponent(workflowName)}`;
-  const triggerRes = await fetchOrExit(triggerUrl, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json"
-    },
-    token,
-    body: JSON.stringify(body)
-  });
-  if (!triggerRes.ok) {
-    const errorText = await triggerRes.text();
-    console.error(`Failed to trigger test run: ${triggerRes.status} ${errorText}`);
-    return false;
-  }
-  const triggerData = await triggerRes.json();
-  if (!triggerData.ok || !triggerData.suiteId) {
-    console.error(`Failed to trigger test run: ${triggerData.error ?? "Unknown error"}`);
-    return false;
-  }
-  const { suiteId } = triggerData;
-  console.log(`Test run started (suite: ${suiteId})`);
-  console.log("Streaming results...\n");
-  const streamUrl = `${apiUrl}/workflows/test-runs/stream?suiteId=${suiteId}`;
-  const streamRes = await fetchOrExit(streamUrl, {
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: "text/event-stream"
-    },
-    token,
-    // SSE connections stay open; don't let the default 30s timeout cut them off.
-    timeoutMs: 0
-  });
-  if (!streamRes.ok || !streamRes.body) {
-    console.error(`Failed to connect to event stream: ${streamRes.status}`);
-    return false;
-  }
-  let success = false;
-  let hasCompleted = false;
-  const parser = createParser({
-    onEvent: (event) => {
-      if (!event.data) return;
-      try {
-        const data = JSON.parse(event.data);
-        if (event.event === "workflow-test") {
-          const testEvent = data;
-          if (testEvent.status === "success") {
-            console.log(`  \u2713 ${workflowName}`);
-            success = true;
-          } else if (testEvent.status === "failed") {
-            console.log(`  \u2717 ${workflowName}`);
-            if (testEvent.errorMessage) {
-              console.log(`    Error: ${testEvent.errorMessage.slice(0, 200)}`);
-            }
-            success = false;
-          } else if (testEvent.status === "running") {
-            console.log(`  \u25B6 Running ${workflowName}...`);
-          }
-        }
-        if (event.event === "workflow-test-suite") {
-          const suiteEvent = data;
-          if (suiteEvent.status === "completed") {
-            hasCompleted = true;
-          }
-        }
-      } catch {
-      }
-    }
-  });
-  const reader = streamRes.body.getReader();
-  const decoder = new TextDecoder();
-  let timedOut = false;
-  const timeoutHandle = setTimeout(() => {
-    timedOut = true;
-    reader.cancel().catch(() => {
-    });
-  }, timeoutMs);
-  try {
-    while (!hasCompleted) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      parser.feed(decoder.decode(value, { stream: true }));
-    }
-  } finally {
-    clearTimeout(timeoutHandle);
-    try {
-      reader.releaseLock();
-    } catch {
-    }
-  }
-  if (!hasCompleted) {
-    const reason = timedOut ? `Timed out after ${Math.round(timeoutMs / 1e3)}s waiting for test completion` : "Event stream closed before completion";
-    console.warn(`
-\u26A0 ${reason}. Polling final state...`);
-    const live = await fetchSuiteLiveState(apiUrl, token, suiteId);
-    const exec = live?.execution;
-    if (exec && (exec.status === "completed" || exec.status === "completed_with_errors")) {
-      success = exec.failedWorkflows === 0;
-      const match = live?.runs?.find((r) => r.workflowId === workflowId);
-      if (match) {
-        console.log(
-          success ? `  \u2713 ${workflowName}` : `  \u2717 ${workflowName}`
-        );
-        if (!success && match.errorMessage) {
-          console.log(`    Error: ${match.errorMessage.slice(0, 200)}`);
-        }
-      }
-    } else {
-      console.error(
-        `Suite ${suiteId} is still ${exec?.status ?? "unknown"} on the server. Check it in the web app.`
-      );
-      return false;
-    }
-  }
-  if (success) {
-    try {
-      const publishRes = await fetchOrExit(`${apiUrl}/workflows/${workflowId}/publish`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json"
-        },
-        token
-      });
-      if (publishRes.ok) {
-        console.log(`
-\u2713 Workflow published successfully`);
-        return true;
-      } else {
-        console.error(`
-Failed to publish workflow: ${publishRes.status}`);
-        return false;
-      }
-    } catch (err) {
-      console.error(`
-Failed to publish workflow: ${err}`);
-      return false;
-    }
-  }
-  console.log(`
-\u2717 Test failed \u2014 workflow left in draft for manual review`);
-  return false;
-}
 async function readApiSequenceConfig(argv) {
   const fromFile = getArgValue(argv, "--sequence-from-file");
   const fromStdin = hasFlag(argv, "--sequence-from-stdin");
@@ -409,13 +252,10 @@ async function handleWorkflowCreate(argv, apiUrl, token) {
     await handleApiOnlyCreate(argv, apiUrl, token);
     return;
   }
-  const runAndPublishFlag = hasFlag(argv, "--run-and-publish");
-  const propertyArg = getArgValue(argv, "--property");
-  const environmentArg = getArgValue(argv, "--environment");
-  const timeoutArg = getArgValue(argv, "--publish-timeout");
-  const timeoutSec = timeoutArg ? Number.parseInt(timeoutArg, 10) : 900;
-  if (!Number.isFinite(timeoutSec) || timeoutSec <= 0) {
-    console.error(`Error: --publish-timeout must be a positive integer (seconds), got "${timeoutArg}"`);
+  if (hasFlag(argv, "--run-and-publish")) {
+    console.error(
+      "Error: --run-and-publish was removed. Run the test (canary workflow run <id>), then\napprove it (canary workflow approve <id> --yes) and promote it (canary workflow promote <id>)."
+    );
     process2.exit(1);
   }
   let input;
@@ -495,21 +335,10 @@ Error applying tags:
 ${err instanceof Error ? err.message : String(err)}`);
     process2.exit(1);
   }
-  if (runAndPublishFlag) {
-    console.log("\nTriggering test run...");
-    const passed = await runAndPublish({
-      apiUrl,
-      token,
-      workflowId: workflow.id,
-      workflowName: workflow.name,
-      propertyId: propertyArg ?? input.propertyId,
-      environmentId: environmentArg,
-      timeoutMs: timeoutSec * 1e3
-    });
-    if (!passed) {
-      process2.exit(1);
-    }
-  }
+  console.log(
+    `
+  Next: run it (canary workflow run ${workflow.id}), approve it (canary workflow approve ${workflow.id} --yes), then promote it into suites (canary workflow promote ${workflow.id}).`
+  );
 }
 
 // src/workflow-run.ts
@@ -1246,7 +1075,7 @@ async function handleWorkflowSync(argv, apiUrl, token) {
 
 // src/workflow-api-sequence.ts
 import process6 from "process";
-import { createParser as createParser2 } from "eventsource-parser";
+import { createParser } from "eventsource-parser";
 async function handleWorkflowGenerateApiSequence(argv, apiUrl, token) {
   const workflowId = argv.find((a) => !a.startsWith("-"));
   const prompt = getArgValue(argv, "--prompt");
@@ -1331,7 +1160,7 @@ async function handleWorkflowGenerateApiSequence(argv, apiUrl, token) {
   let resultSummary = "";
   let hasCompleted = false;
   let exitCode = 0;
-  const parser = createParser2({
+  const parser = createParser({
     onEvent: (event) => {
       if (!event.data || event.event !== "api-sequence-generation") return;
       try {
@@ -2086,7 +1915,7 @@ ACTION
 
 ASSERTION
   Verifies expected outcomes. Define a condition to check.
-  The run fails if the condition is not met.
+  What happens on failure depends on the severity.
 
   Prefer inline assertions on action nodes over standalone assertion nodes.
   Inline assertions keep the test on track and produce cleaner failure
@@ -2098,8 +1927,11 @@ ASSERTION
   confirming data absence after a sequence of steps.
 
   Severity levels:
-    fail    Critical \u2014 the test stops if this fails
-    warn    Non-critical \u2014 logged but doesn't fail the test
+    fatal   The test must end now \u2014 the run halts at this step.
+            Use for preconditions later steps depend on.
+    fail    The test may continue \u2014 the run finishes marked failed,
+            but later steps still run and produce signal.
+    warn    The test should continue \u2014 logged as a warning, run passes.
 
   Agentic assertions: for visual/layout checks that can't be mechanically
   validated, enable agent evaluation. These require the AI agent during
@@ -2157,6 +1989,37 @@ API SEQUENCE
   browser-based seed to discover the right API calls, then convert
   to an API sequence for speed and reliability.
 
+SANDBOX ACTION
+  Executes a sandbox action \u2014 a server-side script defined on the
+  environment template \u2014 directly on the run environment's sandbox
+  instance. No browser involved. The action's structured output is
+  registered as workflow variables: each output key becomes
+  $var.{key} for downstream steps.
+
+  Config:
+    actionSlug   Slug of the action (required; discover via
+                 list_sandbox_actions)
+    params       Input values keyed by the action's inputSchema
+                 property names; values may use $var.{name} / macros
+    outputKeys   Output variable keys (defaults to the action's
+                 outputSchema keys)
+
+  Output registration is allowlisted by declared intent: the action's
+  outputSchema keys, else the node's outputKeys. If neither declares
+  anything, NO result keys register \u2014 declare outputs explicitly for
+  schema-less actions.
+
+  Environment constraint: the action runs on the environment's
+  backing sandbox instance. On a non-sandbox environment (static
+  staging/prod) the node SKIPS with a warning and registers no
+  variables \u2014 so workflows containing one are effectively
+  sandbox-only.
+
+  Seeds: a seed workflow whose body is a single sandbox action node
+  is the fastest way to provision data \u2014 it runs entirely
+  server-side (no browser session), and its outputs satisfy the
+  seed's declared outputs like any captured value.
+
 NOTIFICATION
   Sends notifications (Slack, email, etc.) at a point in the workflow.
 
@@ -2634,6 +2497,23 @@ TEARDOWN WORKFLOWS
   Teardowns are the cleanest way to handle cleanup \u2014 they keep cleanup
   logic separate from test logic and run automatically.
 
+SANDBOX-ACTION-BACKED SEEDS
+
+  When the property has a verified sandbox template with actions, a seed
+  workflow can provision data by running a SANDBOX ACTION node instead of
+  driving the UI or composing API calls. The seed's body is a single
+  sandbox_action node (plus End); the action's outputs register as
+  $var.{key} and satisfy the seed's declared outputs directly.
+
+  - Fastest seed form: runs entirely server-side, no browser session
+  - Discover actions with list_sandbox_actions; outputs come from the
+    action's outputSchema
+  - Constraint: consuming workflows become sandbox-only \u2014 on a
+    non-sandbox environment the action node skips with a warning and
+    produces no variables
+  - Teardown is usually unnecessary: sandbox environments are destroyed
+    after the suite, taking provisioned data with them
+
 SEED BEST PRACTICES
 
   - Use macros in all created data ($EMAIL, $RANDOM_STRING, etc.)
@@ -2643,6 +2523,8 @@ SEED BEST PRACTICES
   - Export only what downstream workflows need \u2014 don't over-export
   - Start with browser-based seeds, then use auto-conversion to generate
     an API sequence from a completed run
+  - For sandbox-backed properties, prefer a sandbox-action-backed seed
+    (see above) \u2014 server-side, fast, and reliable
   - Pair seeds with teardown workflows for automatic cleanup
   - Use suite-level setup nodes to share seed data across multiple
     workflows in the same test suite
@@ -2771,13 +2653,31 @@ INLINE ASSERTIONS (PREFERRED)
     Action: "Submit the support ticket"
     Inline assertions:
       - "Success toast appears" (severity: warn)
-      - "Form is no longer visible" (severity: fail)
-
-  Severity levels:
-    fail    Critical \u2014 the test stops if this fails.
-            Use for: data saved, redirect happened, error absent.
-    warn    Non-critical \u2014 logged but doesn't fail the test.
-            Use for: toast appeared, animation completed.
+      - "Ticket appears in the ticket list" (severity: fail)
+      - "Form is no longer visible" (severity: fatal)
+
+  Severity levels \u2014 what a failure means for the run:
+    fatal   The test must end now. The run halts at this step.
+            Use when continuing is pointless: login succeeded, the page
+            loaded, a precondition every later step depends on.
+            Example: "User is logged in and the dashboard is visible"
+    fail    The test may continue. The step is marked failed and the run
+            finishes marked failed, but later steps still execute and
+            produce signal.
+            Use for independent checks: data saved, expected row present,
+            error absent.
+            Example: "The new record appears in the table"
+    warn    The test should continue. The failure is recorded as a warning
+            and the run still passes.
+            Use for cosmetic or non-critical checks: toast appeared,
+            animation completed.
+            Example: "Success toast appears"
+
+  Choosing a severity: ask "if this is wrong, is there any value in
+  running the rest of the test?" No \u2192 fatal. "Does this being wrong mean
+  the feature is broken?" Yes \u2192 fail. Otherwise \u2192 warn. When unsure,
+  prefer fatal for preconditions and fail for feature claims. Always set
+  a severity explicitly \u2014 don't leave it unspecified.
 
   If verifying something requires significant interaction (scrolling,
   navigating, expanding sections), model that as an action node with
@@ -2876,8 +2776,8 @@ var WORKFLOW_GUIDE_SECTIONS = [
 
 // src/workflow.ts
 var WORKFLOW_STATUS_DESCRIPTIONS = {
-  draft: "editable, not run by suites",
-  published: "active, included in regression runs"
+  draft: "not yet approved \u2014 no human has signed off on the spec",
+  approved: "a human verified the test checks the right thing"
 };
 var formatWorkflowStatusList = () => USER_SETTABLE_WORKFLOW_STATUSES.map(
   (s) => `${s} (${WORKFLOW_STATUS_DESCRIPTIONS[s]})`
@@ -2966,6 +2866,7 @@ function formatWorkflowMarkdown(workflow) {
 function formatWorkflowJson(workflow) {
   const sorted = [...workflow.nodes].sort((a, b) => a.orderIndex - b.orderIndex);
   const seedOutputs = workflow.seedOutputsJson;
+  const env = workflow;
   return {
     workflow: {
       id: workflow.id,
@@ -2973,7 +2874,18 @@ function formatWorkflowJson(workflow) {
       description: workflow.description,
       status: workflow.status,
       flowType: workflow.flowType,
-      ...seedOutputs && seedOutputs.length > 0 ? { seedOutputs } : {}
+      ...seedOutputs && seedOutputs.length > 0 ? { seedOutputs } : {},
+      ...env.defaultEnvironmentId !== void 0 ? { defaultEnvironmentId: env.defaultEnvironmentId } : {},
+      ...env.eligibleEnvironmentIds ? { eligibleEnvironmentIds: env.eligibleEnvironmentIds } : {},
+      ...env.passByEnvironment && env.passByEnvironment.length > 0 ? {
+        passByEnvironment: env.passByEnvironment.map((p) => ({
+          environment: `${p.environmentName} (${p.environmentType})`,
+          everPassed: p.everPassed,
+          passed: p.passed,
+          total: p.total,
+          health: p.health
+        }))
+      } : {}
     },
     steps: sorted.map((node, i) => ({
       index: i + 1,
@@ -3098,7 +3010,7 @@ async function handlePatch(argv, apiUrl, token) {
   const workflowId = argv.find((a) => !a.startsWith("-"));
   if (!workflowId) {
     console.error("Error: Missing workflow ID.");
-    console.error("Usage: canary workflow patch <workflowId> [--name ...] [--description ...] [--status ...] [--flow-type ...]");
+    console.error("Usage: canary workflow patch <workflowId> [--name ...] [--description ...] [--status ...] [--flow-type ...] [--default-environment <name|id>] [--clear-default-environment] [--any-environment] [--eligible-env-types permanent,sandbox] [--eligible-environments <names|ids>]");
     process9.exit(1);
   }
   const name = getArgValue(argv, "--name");
@@ -3108,10 +3020,28 @@ async function handlePatch(argv, apiUrl, token) {
   const seedOutputsJsonRaw = getArgValue(argv, "--seed-outputs-json");
   const seedOutputsFile = getArgValue(argv, "--seed-outputs-file");
   const jsonOutput = hasFlag(argv, "--json");
+  const defaultEnvironment = getArgValue(argv, "--default-environment");
+  const clearDefaultEnvironment = hasFlag(argv, "--clear-default-environment");
+  const anyEnvironment = hasFlag(argv, "--any-environment");
+  const eligibleEnvTypes = getArgValue(argv, "--eligible-env-types");
+  const eligibleEnvironments = getArgValue(argv, "--eligible-environments");
+  const hasEnvFlag = defaultEnvironment !== void 0 || clearDefaultEnvironment || anyEnvironment || eligibleEnvTypes !== void 0 || eligibleEnvironments !== void 0;
   const hasTagFlag = getArgValue(argv, "--tags") !== void 0 || getArgValue(argv, "--tags-add") !== void 0 || getArgValue(argv, "--tags-remove") !== void 0 || getArgValue(argv, "--tag-id") !== void 0;
-  if (!name && !description && !status && !flowType && !seedOutputsJsonRaw && !seedOutputsFile && !hasTagFlag) {
+  if (!name && !description && !status && !flowType && !seedOutputsJsonRaw && !seedOutputsFile && !hasTagFlag && !hasEnvFlag) {
     console.error(
-      "Error: No fields to update. Provide at least one of: --name, --description, --status, --flow-type, --seed-outputs-json, --seed-outputs-file, --tags, --tags-add, --tags-remove, --tag-id"
+      "Error: No fields to update. Provide at least one of: --name, --description, --status, --flow-type, --seed-outputs-json, --seed-outputs-file, --tags, --tags-add, --tags-remove, --tag-id, --default-environment, --clear-default-environment, --any-environment, --eligible-env-types, --eligible-environments"
+    );
+    process9.exit(1);
+  }
+  if (anyEnvironment && (eligibleEnvTypes !== void 0 || eligibleEnvironments !== void 0)) {
+    console.error(
+      "Error: --any-environment is mutually exclusive with --eligible-env-types / --eligible-environments."
+    );
+    process9.exit(1);
+  }
+  if (clearDefaultEnvironment && defaultEnvironment !== void 0) {
+    console.error(
+      "Error: --clear-default-environment is mutually exclusive with --default-environment."
     );
     process9.exit(1);
   }
@@ -3156,6 +3086,47 @@ async function handlePatch(argv, apiUrl, token) {
       process9.exit(1);
     }
   }
+  if (hasEnvFlag) {
+    if (anyEnvironment) body.environmentConstraints = null;
+    if (eligibleEnvTypes !== void 0) {
+      const types = eligibleEnvTypes.split(",").map((t) => t.trim()).filter(Boolean);
+      const valid = ["permanent", "ephemeral", "local", "sandbox"];
+      const bad = types.filter((t) => !valid.includes(t));
+      if (bad.length > 0) {
+        console.error(`Error: invalid env type(s): ${bad.join(", ")}. Valid: ${valid.join(", ")}`);
+        process9.exit(1);
+      }
+      body.environmentConstraints = { mode: "envTypes", types };
+    }
+    if (clearDefaultEnvironment) body.defaultEnvironmentId = null;
+    const needsResolution = defaultEnvironment !== void 0 || eligibleEnvironments !== void 0;
+    if (needsResolution) {
+      const detailRes = await apiRequest(
+        apiUrl,
+        token,
+        "GET",
+        `/workflows/${workflowId}`
+      );
+      const envs = detailRes.workflow?.environments ?? [];
+      const resolveEnv = (nameOrId) => {
+        const match = envs.find((e) => e.id === nameOrId) ?? envs.find((e) => e.name.toLowerCase() === nameOrId.toLowerCase());
+        if (!match) {
+          console.error(
+            `Error: environment "${nameOrId}" not found on this flow's property. Known: ${envs.map((e) => `${e.name} (${e.type})`).join(", ") || "(none)"}`
+          );
+          process9.exit(1);
+        }
+        return match.id;
+      };
+      if (defaultEnvironment !== void 0) {
+        body.defaultEnvironmentId = resolveEnv(defaultEnvironment);
+      }
+      if (eligibleEnvironments !== void 0) {
+        const ids = eligibleEnvironments.split(",").map((t) => t.trim()).filter(Boolean).map(resolveEnv);
+        body.environmentConstraints = { mode: "only", environmentIds: ids };
+      }
+    }
+  }
   let tagResult = null;
   if (Object.keys(body).length > 0) {
     const result = await apiRequest(
@@ -3288,41 +3259,129 @@ async function handleUnarchive(argv, apiUrl, token) {
     console.log(`Restored workflow ${workflowId}.`);
   }
 }
-async function handlePublish(argv, apiUrl, token) {
+var APPROVAL_GUIDANCE = [
+  "Approving a test asserts that a HUMAN has verified it tests the right thing.",
+  "",
+  "If you are an agent running this command on behalf of a user:",
+  "  - Describe to the user what this test does and what approval means.",
+  "  - Confirm the user has personally verified the test is correct.",
+  "  - Only re-run with --yes after the user explicitly confirms.",
+  "",
+  "Approval does NOT put the test into suites \u2014 use `canary workflow promote` for that."
+].join("\n");
+async function handleApprove(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow approve <workflowId> [--yes] [--json]");
+    process9.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  if (!hasFlag(argv, "--yes")) {
+    console.error(APPROVAL_GUIDANCE);
+    console.error(`
+Re-run with --yes to approve: canary workflow approve ${workflowId} --yes`);
+    process9.exit(1);
+  }
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/workflows/${workflowId}/approve`,
+    {}
+  );
+  if (result.error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.error}`);
+    }
+    process9.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({ ok: true, workflowId, workflow: result.workflow ?? null }, null, 2)
+    );
+    return;
+  }
+  console.log(`Workflow ${workflowId} approved.`);
+  console.log(`Promote it into suites with: canary workflow promote ${workflowId}`);
+}
+async function handlePromote(argv, apiUrl, token, options) {
   const workflowId = argv.find((a) => !a.startsWith("-"));
   if (!workflowId) {
     console.error("Error: Missing workflow ID.");
-    console.error("Usage: canary workflow publish <workflowId> [--force] [--json]");
+    console.error("Usage: canary workflow promote <workflowId> [--force] [--json]");
     process9.exit(1);
   }
   const force = hasFlag(argv, "--force");
   const jsonOutput = hasFlag(argv, "--json");
+  if (options?.deprecatedAlias && !jsonOutput) {
+    console.error(
+      `Note: \`canary workflow ${options.deprecatedAlias}\` is deprecated \u2014 use \`canary workflow promote\`.`
+    );
+  }
   const result = await apiRequest(
     apiUrl,
     token,
     "POST",
-    `/workflows/${workflowId}/publish`,
+    `/workflows/${workflowId}/promote`,
     force ? { force: true } : {}
   );
   if (result.error) {
     if (jsonOutput) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      const hint = result.code === "FLOW_NOT_READY_TO_PUBLISH" ? "\n  Trigger a successful run first (canary workflow run <id>), or pass --force." : "";
+      const hint = result.code === "FLOW_NOT_READY_TO_PUBLISH" ? "\n  Trigger a successful run first (canary workflow run <id>), or pass --force." : result.code === "PROMOTION_REQUIRES_APPROVAL" ? `
+  Approve the test first: canary workflow approve ${workflowId} --yes
+  (Approval asserts a human verified the test checks the right thing \u2014 it cannot be forced.)` : "";
       console.error(`Error: ${result.error}${hint}`);
     }
     process9.exit(1);
   }
-  const version = result.workflow?.snapshotVersion;
   if (jsonOutput) {
     console.log(
       JSON.stringify({ ok: true, workflowId, workflow: result.workflow ?? null }, null, 2)
     );
     return;
   }
-  console.log(
-    `Workflow ${workflowId} published${version !== void 0 ? ` as snapshot v${version}` : ""}.`
+  console.log(`Workflow ${workflowId} promoted \u2014 it will run when test suites run.`);
+}
+async function handlePause(argv, apiUrl, token) {
+  const workflowId = argv.find((a) => !a.startsWith("-"));
+  if (!workflowId) {
+    console.error("Error: Missing workflow ID.");
+    console.error("Usage: canary workflow pause <workflowId> [--json]");
+    process9.exit(1);
+  }
+  const jsonOutput = hasFlag(argv, "--json");
+  const result = await apiRequest(
+    apiUrl,
+    token,
+    "POST",
+    `/workflows/${workflowId}/pause`,
+    {}
   );
+  if (result.error) {
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.error}`);
+    }
+    process9.exit(1);
+  }
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({ ok: true, workflowId, workflow: result.workflow ?? null }, null, 2)
+    );
+    return;
+  }
+  const promotion = result.workflow?.promotion ?? null;
+  if (promotion === "paused") {
+    console.log(`Workflow ${workflowId} paused \u2014 excluded from suite runs until re-promoted.`);
+  } else {
+    console.log(`Workflow ${workflowId} was not promoted; nothing to pause.`);
+  }
 }
 function getAllArgValues2(argv, flag) {
   const values = [];
@@ -3455,7 +3514,10 @@ function printWorkflowHelp() {
       "  create [options]                            Create workflow from JSON",
       "  sync <workflowId> [options]                 Replace all nodes (same format as create)",
       "  patch <workflowId> [options]                Update workflow properties",
-      "  publish <workflowId> [--force] [--json]     Promote the current draft to a new published snapshot",
+      "  approve <workflowId> [--yes] [--json]       Mark the test as human-verified (spec is right)",
+      "  promote <workflowId> [--force] [--json]     Include the test in suite runs (requires approval)",
+      "  pause <workflowId> [--json]                 Exclude a promoted test from suite runs",
+      "  publish <workflowId> [--force] [--json]     (deprecated alias for promote)",
       "  archive <workflowId> [--yes] [--json]       Soft-delete: hide from lists, skip in test suites (reversible)",
       "  unarchive <workflowId> [--json]             Restore a previously archived workflow",
       "  run <workflowId> [options]                  Trigger a workflow execution",
@@ -3469,7 +3531,7 @@ function printWorkflowHelp() {
       "List options:",
       "  --search <query>      Search by name",
       "  --flow-type <type>    Filter: standard, setup, seed, teardown",
-      "  --status <status>     Filter: draft, published",
+      "  --status <status>     Filter: draft, approved",
       "  --page <n>            Page number (default: 1)",
       "  --page-size <n>       Page size (default: 25)",
       "  --json                Output raw JSON",
@@ -3477,7 +3539,7 @@ function printWorkflowHelp() {
       "Get options:",
       "  --format json|markdown|spec  Output format (default: json)",
       "  --json                  Shorthand for --format json",
-      "  --markdown              Shorthand for editable .canary.md spec output",
+      `  --markdown              Shorthand for editable ${specExtension} spec output`,
       "  --output <file>         Write output to file",
       "",
       "Create options:",
@@ -3489,10 +3551,6 @@ function printWorkflowHelp() {
       "                                    --sequence-from-file <path> or --sequence-from-stdin",
       "                          Input shape: { steps, description?, stopOnFailure?, exports? }",
       "                          Returns: { workflowId, apiSequenceId, nodeId }",
-      "  --run-and-publish       Run test first, publish on success",
-      "  --publish-timeout <sec> Timeout waiting for the test to finish (default: 900)",
-      "  --property <name|id>    Property for run-and-publish",
-      "  --environment <name|id> Environment for run-and-publish",
       "  --tags <names>          Comma-separated tag names to assign (names, not IDs)",
       "  --tag-id <ids>          Comma-separated raw tag IDs (escape hatch)",
       "",
@@ -3521,10 +3579,11 @@ function printWorkflowHelp() {
       "Patch options:",
       "  --name <name>           Update workflow name",
       "  --description <desc>    Update description",
-      "  --status <status>       Set status. Valid:",
-      "                            draft       \u2014 editable, not run by suites",
-      "                            published   \u2014 active, included in regression runs",
-      "                          (reliability is tracked automatically by health)",
+      "  --status <status>       Set status (approval axis). Valid:",
+      "                            draft       \u2014 not yet approved",
+      "                            approved    \u2014 a human verified the test checks the right thing",
+      "                          (suite inclusion is the separate promote/pause axis;",
+      "                           reliability is tracked automatically by health)",
       "  --flow-type <type>      Set type: standard, setup, seed, teardown",
       "  --seed-outputs-json <json>   Replace seedOutputsJson (array) \u2014 seed flows only",
       "  --seed-outputs-file <path>   Replace seedOutputsJson from a JSON file",
@@ -3534,15 +3593,22 @@ function printWorkflowHelp() {
       "  --tag-id <ids>          Raw tag IDs (comma-separated)",
       "  --json                  Output raw JSON",
       "",
-      "Publish options:",
-      "  --force                 Publish without requiring a successful run (skips the",
-      "                          ready-to-publish gate; the new snapshot has no linked run)",
+      "Approve options:",
+      "  --yes                   Confirm approval (required non-interactively)",
       "  --json                  Output raw JSON",
       "",
-      "  Publish snapshots the current workflow definition and promotes it",
-      "  into the suite. Without --force, the workflow must have a passing",
-      "  run (ready_to_publish=true). Different from --status=published which",
-      "  only sets a column and does NOT create a new snapshot.",
+      "  Approval asserts a human verified the test checks the right thing.",
+      "  Agents: describe the test to the user and confirm they personally",
+      "  verified it before re-running with --yes.",
+      "",
+      "Promote options:",
+      "  --force                 Promote without requiring a successful run (skips the",
+      "                          run gate; the approval gate can never be forced)",
+      "  --json                  Output raw JSON",
+      "",
+      "  Promote includes the test in suite runs. Suites always execute the",
+      "  live definition \u2014 edits take effect immediately. Requires the test",
+      "  to be approved, and (without --force) a passing run.",
       "",
       "Run options:",
       "  --stream                Follow execution until completion",
@@ -3591,7 +3657,7 @@ function printWorkflowHelp() {
       "                                                            Targeted cache invalidation (rows kept, isValid=false)",
       "  cache clear <workflowId> --mode hard --yes               DESTRUCTIVE: delete cache rows, strip playbookSteps,",
       '                                                            null lastRunId. Same as the UI "Reset flow" button',
-      "  cache optimize <workflowId>                              Enqueue a shadow-cache-writer heal run",
+      "  cache optimize <workflowId> [--run <runId>]              Enqueue the async cache-optimizer job",
       "",
       "Common options:",
       "  --env <env>           Target environment (prod, dev, local)",
@@ -3607,7 +3673,7 @@ async function runWorkflow(argv) {
     return;
   }
   if (subCommand === "debug" && hasFlag(rest, "--help", "-h")) {
-    const { handleWorkflowDebug } = await import("./workflow-debug-BGD4UIXU.js");
+    const { handleWorkflowDebug } = await import("./workflow-debug-T2BULXZ7.js");
     await handleWorkflowDebug(rest, "", "");
     return;
   }
@@ -3635,8 +3701,17 @@ async function runWorkflow(argv) {
     case "patch":
       await handlePatch(rest, apiUrl, token);
       break;
+    case "approve":
+      await handleApprove(rest, apiUrl, token);
+      break;
+    case "promote":
+      await handlePromote(rest, apiUrl, token);
+      break;
+    case "pause":
+      await handlePause(rest, apiUrl, token);
+      break;
     case "publish":
-      await handlePublish(rest, apiUrl, token);
+      await handlePromote(rest, apiUrl, token, { deprecatedAlias: "publish" });
       break;
     case "archive":
       await handleArchive(rest, apiUrl, token);
@@ -3676,7 +3751,7 @@ async function runWorkflow(argv) {
       await handleWorkflowSync(rest, apiUrl, token);
       break;
     case "proposals": {
-      const { handleWorkflowProposals } = await import("./workflow-proposals-MTUDX46O.js");
+      const { handleWorkflowProposals } = await import("./workflow-proposals-XXEZICN2.js");
       await handleWorkflowProposals(rest, apiUrl, token);
       break;
     }
@@ -3687,12 +3762,12 @@ async function runWorkflow(argv) {
       await handleWorkflowApiSequence(rest, apiUrl, token);
       break;
     case "cache": {
-      const { handleWorkflowCache } = await import("./workflow-cache-NQJQFWMV.js");
+      const { handleWorkflowCache } = await import("./workflow-cache-XVEZ36KF.js");
       await handleWorkflowCache(rest, apiUrl, token);
       break;
     }
     case "debug": {
-      const { handleWorkflowDebug } = await import("./workflow-debug-BGD4UIXU.js");
+      const { handleWorkflowDebug } = await import("./workflow-debug-T2BULXZ7.js");
       await handleWorkflowDebug(rest, apiUrl, token);
       break;
     }
@@ -3705,4 +3780,4 @@ async function runWorkflow(argv) {
 export {
   runWorkflow
 };
-//# sourceMappingURL=workflow-XYFH5LTP.js.map
+//# sourceMappingURL=workflow-T4HSAOGW.js.map