@getmagical/cli 0.3.2 → 0.6.0

package/dist/index.js

@@ -6954,6 +6954,130 @@ function renderKeyValueBlock(entries) {
 function renderSection(title, bodyLines) {
   return [formatHeading(title), "", ...bodyLines].join("\n");
 }
+function getRecordArray(value) {
+  return Array.isArray(value) && value.every(isRecord) ? value : null;
+}
+function getRecordScalar(record, key) {
+  const value = record[key];
+  return isPrimitiveLike(value) ? formatScalar(value) : EMPTY_VALUE;
+}
+function getMergeChangeExplanation(change) {
+  const explanation = change["statusDescription"] ?? change["conflictDescription"];
+  return typeof explanation === "string" ? formatScalar(explanation) : EMPTY_VALUE;
+}
+function formatMergeChanges(changes, includeStatus) {
+  return formatTable({
+    columns: includeStatus ? ["Change", "Status", "Discardable", "Explanation", "Change ID"] : ["Change", "Explanation", "Change ID"],
+    rows: changes.map((change) => {
+      const cells = [getRecordScalar(change, "label")];
+      if (includeStatus) {
+        cells.push(
+          getRecordScalar(change, "status"),
+          change["discardable"] === true ? "yes" : "no"
+        );
+      }
+      cells.push(
+        getMergeChangeExplanation(change),
+        getRecordScalar(change, "id")
+      );
+      return cells;
+    })
+  });
+}
+function renderMergePreviewSection(title, preview, changes) {
+  return renderSection(title, [
+    renderKeyValueBlock([
+      ["Base version", getRecordScalar(preview, "baseVersionId")],
+      ["Source version", getRecordScalar(preview, "sourceVersionId")],
+      ["Target version", getRecordScalar(preview, "targetVersionId")]
+    ]),
+    "",
+    changes.length > 0 ? formatMergeChanges(changes, true) : "No changes to merge."
+  ]);
+}
+function renderDiscardHint(preview, changes) {
+  const hasDiscardable = changes.some(
+    (change) => change["discardable"] === true
+  );
+  if (!hasDiscardable) {
+    return null;
+  }
+  return renderSection("Resolve conflicts", [
+    "Discards revert a change on the branch so main keeps its value; conflicts must be discarded or edited to match main before merging.",
+    formatCommandSnippet(
+      `mgcl --branch-id <branch-id> automations branches discard-changes --automation-id <automation-id> --change-ids <change-id,...> --source-version-id ${getRecordScalar(preview, "sourceVersionId")} --target-version-id ${getRecordScalar(preview, "targetVersionId")}`
+    )
+  ]);
+}
+function formatAutomationBranchMergePreviewOutput(value) {
+  const changes = isRecord(value) ? getRecordArray(value["changes"]) : null;
+  if (!isRecord(value) || !changes) {
+    return formatHumanReadableOutput(value);
+  }
+  const hint = renderDiscardHint(value, changes);
+  return [
+    renderMergePreviewSection("Merge Preview", value, changes),
+    ...hint ? [hint] : []
+  ].join("\n\n");
+}
+function formatAutomationBranchDiscardOutput(value) {
+  const preview = isRecord(value) ? value["preview"] : null;
+  const changes = isRecord(preview) ? getRecordArray(preview["changes"]) : null;
+  if (!isRecord(value) || !isRecord(preview) || !changes) {
+    return formatHumanReadableOutput(value);
+  }
+  const discardedChangeIds = Array.isArray(value["discardedChangeIds"]) ? value["discardedChangeIds"].map(formatScalar).join(", ") : EMPTY_VALUE;
+  return [
+    renderSection("Branch Discard", [
+      renderKeyValueBlock([
+        ["Branch ID", getRecordScalar(value, "branchId")],
+        ["Previous head", getRecordScalar(value, "previousHeadVersionId")],
+        ["New head", getRecordScalar(value, "headVersionId")],
+        ["Discarded changes", discardedChangeIds]
+      ])
+    ]),
+    renderMergePreviewSection("Refreshed Merge Preview", preview, changes)
+  ].join("\n\n");
+}
+function formatAutomationBranchMergeOutput(value) {
+  if (!isRecord(value) || value["status"] !== "conflict") {
+    return formatHumanReadableOutput(value);
+  }
+  const { preview } = value;
+  const conflicts = getRecordArray(value["conflicts"]);
+  if (!isRecord(preview) || !conflicts || conflicts.length === 0) {
+    return formatHumanReadableOutput(value);
+  }
+  const changes = getRecordArray(preview["changes"]);
+  if (!changes) {
+    return formatHumanReadableOutput(value);
+  }
+  const hint = renderDiscardHint(preview, changes);
+  return [
+    renderSection("Branch Merge", [
+      renderKeyValueBlock([
+        ["Status", getRecordScalar(value, "status")],
+        ["Automation ID", getRecordScalar(value, "automationId")],
+        ["Branch ID", getRecordScalar(value, "branchId")],
+        [
+          "Source branch deleted",
+          getRecordScalar(value, "sourceBranchDeleted")
+        ]
+      ])
+    ]),
+    renderSection("Merge Conflicts", [formatMergeChanges(conflicts, false)]),
+    renderMergePreviewSection("Merge Preview", preview, changes),
+    ...hint ? [hint] : []
+  ].join("\n\n");
+}
+var BRANCH_MERGE_FORMATTERS = /* @__PURE__ */ new Map([
+  ["DiscardAutomationBranchChanges", formatAutomationBranchDiscardOutput],
+  ["MergeAutomationBranch", formatAutomationBranchMergeOutput],
+  ["PreviewAutomationBranchMerge", formatAutomationBranchMergePreviewOutput]
+]);
+function getBranchMergeFormatter(operationName) {
+  return BRANCH_MERGE_FORMATTERS.get(operationName);
+}
 var MagicalHelp = class extends Help {
   outputHasColors = process.stdout.isTTY;
   constructor() {
@@ -7073,12 +7197,14 @@ function formatOutputModesNote() {
 
 // src/errors.ts
 var CliError = class extends Error {
+  apiErrorCode;
   retryAfterMs;
   retryable;
   statusCode;
   constructor(message, options) {
     super(message, options);
     this.name = "CliError";
+    this.apiErrorCode = options?.apiErrorCode;
     this.retryAfterMs = options?.retryAfterMs;
     this.retryable = options?.retryable;
     this.statusCode = options?.statusCode;
@@ -7095,7 +7221,7 @@ function getErrorMessage(error) {
 import { randomUUID as randomUUID4 } from "node:crypto";
 import { readFile as readFile6 } from "node:fs/promises";
 import path8 from "node:path";
-import { setTimeout as sleep } from "node:timers/promises";
+import { setTimeout as sleep2 } from "node:timers/promises";
 
 // ../common/dist/src/stdlib/json.util.js
 var import_ts_essentials = __toESM(require_dist(), 1);
@@ -7767,6 +7893,8 @@ function safeJsonParseWithoutLogging(json) {
 // ../common/dist/src/constants/automation.js
 var AUTOMATION_BRANCH_NAME_MAX_LENGTH = 100;
 var AUTOMATION_BRANCH_NAME_MAX_LENGTH_MESSAGE = `Branch name must be ${AUTOMATION_BRANCH_NAME_MAX_LENGTH} characters or fewer.`;
+var AUTOMATION_BRANCH_DISCARD_MAX_CHANGE_IDS = 50;
+var AUTOMATION_BRANCH_CHANGE_ID_MAX_LENGTH = 256;
 
 // ../common/dist/src/constants/tool-declarations.js
 import { z as z15 } from "zod";
@@ -12365,6 +12493,27 @@ var clickComparisonSchema = z9.union([
     [COMMON_PARAMETERS_KEY]: DEFAULT_COMMON_PARAMETERS
   })
 ]);
+var holdClickMarkerInputSchema = z9.object({
+  marker: markerSchema("The marker of the element to press and hold.")
+});
+var holdClickCoordinateInputSchema = z9.object({
+  coordinates: coordinateSchema({
+    xDescription: "The x coordinate of the element to press and hold.",
+    yDescription: "The y coordinate of the element to press and hold."
+  })
+});
+var holdClickComparisonSchema = z9.union([
+  holdClickMarkerInputSchema.extend({
+    [COMMON_PARAMETERS_KEY]: DEFAULT_COMMON_PARAMETERS
+  }),
+  holdClickCoordinateInputSchema.extend({
+    [COMMON_PARAMETERS_KEY]: DEFAULT_COMMON_PARAMETERS
+  })
+]);
+var releaseClickInputSchema = z9.object({});
+var releaseClickComparisonSchema = releaseClickInputSchema.extend({
+  [COMMON_PARAMETERS_KEY]: DEFAULT_COMMON_PARAMETERS
+});
 var moveMarkerInputSchema = z9.object({
   marker: markerSchema("The marker to move the mouse to")
 });
@@ -12735,7 +12884,8 @@ var PressEvent;
     Response2.create = create;
   })(Response = PressEvent2.Response || (PressEvent2.Response = {}));
 })(PressEvent || (PressEvent = {}));
-var Keys = [
+var ModifierKeys = ["Alt", "Control", "Meta", "Shift"];
+var PhysicalKeys = [
   // Modifiers
   "Alt",
   "CapsLock",
@@ -12837,16 +12987,16 @@ var Keys = [
   "y",
   "Z",
   "z",
-  "0",
-  "1",
-  "2",
-  "3",
-  "4",
-  "5",
-  "6",
-  "7",
-  "8",
-  "9",
+  "Digit0",
+  "Digit1",
+  "Digit2",
+  "Digit3",
+  "Digit4",
+  "Digit5",
+  "Digit6",
+  "Digit7",
+  "Digit8",
+  "Digit9",
   // Punctuation
   "Minus",
   "Equal",
@@ -12863,8 +13013,106 @@ var Keys = [
   "Insert",
   "PrintScreen"
 ];
+var KeyAliases = [
+  "0",
+  "1",
+  "2",
+  "3",
+  "4",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "`",
+  "~",
+  "-",
+  "_",
+  "=",
+  "+",
+  "[",
+  "{",
+  "]",
+  "}",
+  "\\",
+  "|",
+  ";",
+  ":",
+  "'",
+  '"',
+  ",",
+  "<",
+  ".",
+  ">",
+  "/",
+  "?",
+  "!",
+  "@",
+  "#",
+  "$",
+  "%",
+  "^",
+  "&",
+  "*",
+  "(",
+  ")"
+];
+var Keys = [...PhysicalKeys, ...KeyAliases];
+var KeyAliasMappings = [
+  ["0", ["Digit0"]],
+  ["1", ["Digit1"]],
+  ["2", ["Digit2"]],
+  ["3", ["Digit3"]],
+  ["4", ["Digit4"]],
+  ["5", ["Digit5"]],
+  ["6", ["Digit6"]],
+  ["7", ["Digit7"]],
+  ["8", ["Digit8"]],
+  ["9", ["Digit9"]],
+  ["`", ["Backquote"]],
+  ["~", ["Shift", "Backquote"]],
+  ["-", ["Minus"]],
+  ["_", ["Shift", "Minus"]],
+  ["=", ["Equal"]],
+  ["+", ["Shift", "Equal"]],
+  ["[", ["BracketLeft"]],
+  ["{", ["Shift", "BracketLeft"]],
+  ["]", ["BracketRight"]],
+  ["}", ["Shift", "BracketRight"]],
+  ["\\", ["Backslash"]],
+  ["|", ["Shift", "Backslash"]],
+  [";", ["Semicolon"]],
+  [":", ["Shift", "Semicolon"]],
+  ["'", ["Quote"]],
+  ['"', ["Shift", "Quote"]],
+  [",", ["Comma"]],
+  ["<", ["Shift", "Comma"]],
+  [".", ["Period"]],
+  [">", ["Shift", "Period"]],
+  ["/", ["Slash"]],
+  ["?", ["Shift", "Slash"]],
+  ["!", ["Shift", "Digit1"]],
+  ["@", ["Shift", "Digit2"]],
+  ["#", ["Shift", "Digit3"]],
+  ["$", ["Shift", "Digit4"]],
+  ["%", ["Shift", "Digit5"]],
+  ["^", ["Shift", "Digit6"]],
+  ["&", ["Shift", "Digit7"]],
+  ["*", ["Shift", "Digit8"]],
+  ["(", ["Shift", "Digit9"]],
+  [")", ["Shift", "Digit0"]]
+];
+var KeyMappings = [
+  ...PhysicalKeys.map((key) => [
+    key,
+    [key]
+  ]),
+  ...KeyAliasMappings
+];
+var KeyMapping = new Map(KeyMappings);
+var ModifierKeySet = new Set(ModifierKeys);
 var pressDataSchema = z12.object({
-  keys: z12.array(z12.enum(Keys))
+  keys: z12.array(z12.enum(Keys)).describe("Keys in one simultaneous keyboard chord. Use type for a sequence of characters. US keyboard characters and physical key codes such as Digit4 are supported.")
 });
 
 // ../common/dist/src/models/websocket/actions/report-stop.js
@@ -13190,6 +13438,16 @@ var baseToolDeclarations = {
     description: 'ONLY USE FOR CLICKING WITHOUT ENTERING TEXT. This tool clicks on an element but DOES NOT allow entering text. Use for buttons, links, checkboxes, dropdown toggles, tabs, and other clickable elements. NEVER use this when you need to enter text into a field - for text entry, use "clickFill" instead, this tool automatically moves the cursor to the element, no need to use the move tool first.',
     parameters: clickComparisonSchema
   },
+  holdClick: {
+    id: "holdClick",
+    description: "Press and hold the left mouse button on an element that reveals content only while pressed. The hold remains active during non-browser work and is released automatically before the next browser interaction.",
+    parameters: holdClickComparisonSchema
+  },
+  releaseClick: {
+    id: "releaseClick",
+    description: "Release the left mouse button after holdClick. This is safe to call again when the mouse is already released.",
+    parameters: releaseClickComparisonSchema
+  },
   multiClick: {
     id: "multiClick",
     description: "This object is deprecated, only adding here to satisfy the DB type check",
@@ -13798,12 +14056,109 @@ var apiAgentEmbeddedFilesSchema = z16.array(apiAgentEmbeddedFileSchema).superRef
 // ../common/dist/src/zod-schemas/api-agent-request-file-encoding.schema.js
 import { z as z17 } from "zod";
 var API_REQUEST_FILE_PATH_PATTERN = /^[A-Za-z_$][\w$-]*(?:\.[A-Za-z_$][\w$-]*)*$/u;
+var API_REQUEST_BASE64_FILE_HELPER_PATTERN = /^\s*\{\{\s*base64File\s+(?<sourceInput>[^{}\s]+)\s*\}\}\s*$/u;
+var API_REQUEST_BASE64_FILE_HELPER_USAGE_PATTERN = /\{\{\s*base64File\b/u;
+var API_REQUEST_BASE64_FILE_HELPER_EXAMPLE = "{{base64File fileInput}}";
 function parseApiRequestFilePath(path9) {
   if (!API_REQUEST_FILE_PATH_PATTERN.test(path9)) {
     return void 0;
   }
   return path9.split(".");
 }
+function inspectApiRequestBase64FileHelperValue({ path: path9, value }) {
+  const match = API_REQUEST_BASE64_FILE_HELPER_PATTERN.exec(value);
+  if (match === null) {
+    return API_REQUEST_BASE64_FILE_HELPER_USAGE_PATTERN.test(value) ? {
+      helpers: [],
+      issues: [
+        {
+          message: `Use ${API_REQUEST_BASE64_FILE_HELPER_EXAMPLE} as the entire JSON field value.`,
+          path: path9
+        }
+      ]
+    } : { helpers: [], issues: [] };
+  }
+  const { sourceInput } = match.groups ?? {};
+  if (sourceInput === void 0 || parseApiRequestFilePath(sourceInput) === void 0) {
+    return {
+      helpers: [],
+      issues: [
+        {
+          message: "Base64 file helper input must use an object property path.",
+          path: path9
+        }
+      ]
+    };
+  }
+  return {
+    helpers: [{ destinationPath: path9, sourceInput }],
+    issues: []
+  };
+}
+function inspectApiRequestBase64FileHelpers(body, path9 = []) {
+  if (typeof body === "string") {
+    return inspectApiRequestBase64FileHelperValue({ path: path9, value: body });
+  }
+  if (Array.isArray(body)) {
+    return body.reduce((inspection, value, index) => {
+      const nestedInspection = inspectApiRequestBase64FileHelpers(value, [
+        ...path9,
+        index
+      ]);
+      return {
+        helpers: [...inspection.helpers, ...nestedInspection.helpers],
+        issues: [...inspection.issues, ...nestedInspection.issues]
+      };
+    }, { helpers: [], issues: [] });
+  }
+  if (body === null || typeof body !== "object") {
+    return { helpers: [], issues: [] };
+  }
+  return Object.entries(body).reduce((inspection, [key, value]) => {
+    const nestedInspection = inspectApiRequestBase64FileHelpers(value, [
+      ...path9,
+      key
+    ]);
+    return {
+      helpers: [...inspection.helpers, ...nestedInspection.helpers],
+      issues: [...inspection.issues, ...nestedInspection.issues]
+    };
+  }, { helpers: [], issues: [] });
+}
+function validateApiRequestBase64FileHelpers({ body, bodyType, context, supportsRequestBody }) {
+  const inspection = inspectApiRequestBase64FileHelpers(body);
+  for (const issue of inspection.issues) {
+    context.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: issue.message,
+      path: ["body", ...issue.path]
+    });
+  }
+  if (inspection.helpers.length === 0) {
+    return;
+  }
+  if (!supportsRequestBody) {
+    context.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "Base64 file helpers are not supported for this method",
+      path: ["body"]
+    });
+  }
+  if ((bodyType ?? "json") !== "json") {
+    context.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "Base64 file helpers are only supported for JSON bodies",
+      path: ["body"]
+    });
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    context.addIssue({
+      code: z17.ZodIssueCode.custom,
+      message: "Base64 file helpers require a JSON object body",
+      path: ["body"]
+    });
+  }
+}
 var apiAgentRequestFileEncodingSchema = z17.object({
   sourceInput: z17.string().trim().min(1, "File input is required.").refine((path9) => parseApiRequestFilePath(path9) !== void 0, {
     message: "File input must use an object property path."
@@ -13978,6 +14333,13 @@ var apiToolSchema = z20.object({
 }).refine((data) => !data.requestFileEncodings?.length || data.body !== null && typeof data.body === "object" && !Array.isArray(data.body), {
   message: "Request file encoding requires a JSON object body",
   path: ["body"]
+}).superRefine((data, context) => {
+  validateApiRequestBase64FileHelpers({
+    body: data.body,
+    bodyType: data.bodyType,
+    context,
+    supportsRequestBody: methodsWithBody.has(data.type)
+  });
 }).refine((data) => isValidApiMultipartFormDataBody({
   bodyType: data.bodyType,
   body: data.body
@@ -14385,6 +14747,13 @@ var apiAgentConfigSchema = baseAgentConfigFieldsSchema.safeExtend({
 }).refine((data) => !data.requestFileEncodings?.length || data.body !== null && typeof data.body === "object" && !Array.isArray(data.body), {
   message: "Request file encoding requires a JSON object body",
   path: ["body"]
+}).superRefine((data, context) => {
+  validateApiRequestBase64FileHelpers({
+    body: data.body,
+    bodyType: data.bodyType,
+    context,
+    supportsRequestBody: METHODS_WITH_BODY.has(data.method)
+  });
 }).refine((data) => isValidApiMultipartFormDataBody({
   bodyType: data.bodyType,
   body: data.body
@@ -15161,6 +15530,7 @@ ${agentLimitationsSelection}
     operationName: "GetAgentVersion",
     kind: "query",
     inputSchema: z27.object({
+      draftAutomationId: z27.string().min(1),
       agentId: z27.string().min(1),
       versionId: z27.string().min(1)
     }),
@@ -15170,6 +15540,12 @@ ${agentLimitationsSelection}
       description: "Fetch one saved version for an agent.",
       resultKey: "agentVersion",
       options: [
+        stringOption({
+          inputKey: "draftAutomationId",
+          flagName: "automation-id",
+          description: "Automation ID whose main draft lineage scopes the agent's history.",
+          required: true
+        }),
         stringOption({
           inputKey: "agentId",
           flagName: "agent-id",
@@ -15186,8 +15562,12 @@ ${agentLimitationsSelection}
     },
     mcp: { fileName: "agentVersion.graphql" },
     document: `# Query to fetch a specific saved version for an agent
-query GetAgentVersion($agentId: ID!, $versionId: ID!) {
-  agentVersion(agentId: $agentId, versionId: $versionId) {
+query GetAgentVersion($draftAutomationId: ID!, $agentId: ID!, $versionId: ID!) {
+  agentVersion(
+    draftAutomationId: $draftAutomationId
+    agentId: $agentId
+    versionId: $versionId
+  ) {
     id
     agentId
     sequence
@@ -15227,6 +15607,7 @@ ${agentLimitationsSelection}
     operationName: "GetAgentVersions",
     kind: "query",
     inputSchema: z27.object({
+      draftAutomationId: z27.string().min(1),
       agentId: z27.string().min(1)
     }),
     cli: {
@@ -15235,6 +15616,12 @@ ${agentLimitationsSelection}
       description: "Fetch version history for an agent.",
       resultKey: "agentVersions",
       options: [
+        stringOption({
+          inputKey: "draftAutomationId",
+          flagName: "automation-id",
+          description: "Automation ID whose main draft lineage scopes the agent's history.",
+          required: true
+        }),
         stringOption({
           inputKey: "agentId",
           flagName: "agent-id",
@@ -15245,8 +15632,8 @@ ${agentLimitationsSelection}
     },
     mcp: { fileName: "agentVersions.graphql" },
     document: `# Query to fetch version history metadata for an agent
-query GetAgentVersions($agentId: ID!) {
-  agentVersions(agentId: $agentId) {
+query GetAgentVersions($draftAutomationId: ID!, $agentId: ID!) {
+  agentVersions(draftAutomationId: $draftAutomationId, agentId: $agentId) {
     id
     sequence
     name
@@ -15262,6 +15649,7 @@ query GetAgentVersions($agentId: ID!) {
     operationName: "DiffAgentVersion",
     kind: "query",
     inputSchema: z27.object({
+      draftAutomationId: z27.string().min(1),
       agentId: z27.string().min(1),
       versionId: z27.string().min(1),
       compareVersionId: z27.string().min(1).optional()
@@ -15269,9 +15657,15 @@ query GetAgentVersions($agentId: ID!) {
     cli: {
       name: "diff-agent-version",
       path: ["agents", "versions", "diff"],
-      description: "Diff one agent version against another version or the current latest version.",
+      description: "Diff one agent version against another version or the automation's current draft version.",
       resultKey: "agentVersionDiff",
       options: [
+        stringOption({
+          inputKey: "draftAutomationId",
+          flagName: "automation-id",
+          description: "Automation ID whose main draft lineage scopes the agent's history.",
+          required: true
+        }),
         stringOption({
           inputKey: "agentId",
           flagName: "agent-id",
@@ -15287,18 +15681,20 @@ query GetAgentVersions($agentId: ID!) {
         stringOption({
           inputKey: "compareVersionId",
           flagName: "compare-version-id",
-          description: "Optional target version ID. Defaults to the current latest version."
+          description: "Optional target version ID. Defaults to the automation's current draft version."
         })
       ]
     },
     mcp: { fileName: "agentVersionDiff.graphql" },
-    document: `# Query to diff one agent version against another or the current latest version
+    document: `# Query to diff one agent version against another or the automation's current draft version
 query DiffAgentVersion(
+  $draftAutomationId: ID!
   $agentId: ID!
   $versionId: ID!
   $compareVersionId: ID
 ) {
   agentVersionDiff(
+    draftAutomationId: $draftAutomationId
     agentId: $agentId
     versionId: $versionId
     compareVersionId: $compareVersionId
@@ -15340,6 +15736,7 @@ query DiffAgentVersion(
 query GetAgentRun($id: ID!) {
   agentRun(id: $id) {
     id
+    agentId
     agentVersionId
     agentName
     status
@@ -15566,12 +15963,15 @@ query GetAutomationRun($id: ID!) {
   automationRun(id: $id) {
     id
     automationId
+    automationVersionId
     parentAutomationRunId
     status
     statusDetail
     summary
     invocationType
     input
+    initialStore
+    currentStore
     additionalPrompt
     debugUrl
     createdAt
@@ -15606,6 +16006,7 @@ query GetAutomationRun($id: ID!) {
 query GetAutomationRunAgentRuns($automationRunId: ID!) {
   automationRunAgentRuns(automationRunId: $automationRunId) {
     id
+    agentId
     agentVersionId
     agentName
     status
@@ -15625,6 +16026,7 @@ query GetAutomationRunAgentRuns($automationRunId: ID!) {
       automationRunId: z27.string().min(1),
       agentRunId: z27.string().min(1).optional(),
       limit: z27.number().int().positive().optional(),
+      page: z27.number().int().nonnegative().optional(),
       reverse: z27.boolean().optional()
     }),
     cli: {
@@ -15649,6 +16051,11 @@ query GetAutomationRunAgentRuns($automationRunId: ID!) {
           flagName: "limit",
           description: "Maximum number of iterations to return."
         }),
+        numberOption({
+          inputKey: "page",
+          flagName: "page",
+          description: "Zero-based page number."
+        }),
         booleanOption({
           inputKey: "reverse",
           flagName: "reverse",
@@ -15662,18 +16069,21 @@ query GetAutomationRunIterations(
   $automationRunId: ID!
   $agentRunId: ID
   $limit: Int
+  $page: Int
   $reverse: Boolean
 ) {
   automationRunIterations(
     automationRunId: $automationRunId
     agentRunId: $agentRunId
     limit: $limit
+    page: $page
     reverse: $reverse
   ) {
     id
     sequence
     agentRunId
     metadata
+    store
     startedAt
     finishedAt
     totalDurationMs
@@ -15689,6 +16099,42 @@ query GetAutomationRunIterations(
       screenshotMimeType
     }
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetIterationScreenshot",
+    kind: "query",
+    inputSchema: z27.object({
+      iterationId: z27.string().min(1),
+      hasMarks: z27.boolean().default(false)
+    }),
+    cli: {
+      name: "get-iteration-screenshot",
+      path: ["automation-runs", "iteration-screenshot"],
+      description: "Fetch a fresh screenshot URL for an iteration.",
+      resultKey: "iterationScreenshot",
+      options: [
+        stringOption({
+          inputKey: "iterationId",
+          flagName: "iteration-id",
+          description: "Automation run iteration ID.",
+          required: true
+        }),
+        booleanOption({
+          inputKey: "hasMarks",
+          flagName: "with-marks",
+          description: "Fetch the marked screenshot instead of the base screenshot."
+        })
+      ]
+    },
+    mcp: { fileName: "iterationScreenshot.graphql" },
+    document: `# Fetch a fresh screenshot URL for an automation run iteration
+query GetIterationScreenshot($iterationId: ID!, $hasMarks: Boolean = false) {
+  iterationScreenshot(iterationId: $iterationId, hasMarks: $hasMarks) {
+    status
+    url
+    mimeType
+  }
 }`
   }),
   createOperationSpec({
@@ -15777,6 +16223,7 @@ query GetAutomationRuns(
   ) {
     id
     automationId
+    automationVersionId
     parentAutomationRunId
     status
     statusDetail
@@ -15825,6 +16272,7 @@ query GetAutomationRunsPage(
     items {
       id
       automationId
+      automationVersionId
       parentAutomationRunId
       status
       statusDetail
@@ -16123,7 +16571,7 @@ query GetAutomationBranch($automationId: ID!, $branchId: ID!) {
       branchContext: "required",
       name: "merge-automation-branch",
       path: ["automations", "branches", "merge"],
-      description: "Preview and merge a branch into main when every change is conflict-free. Exits nonzero when conflicts block the merge.",
+      description: "Preview and merge a branch into main when every change is conflict-free. Exits nonzero when conflicts block the merge; use `automations branches discard-changes` to resolve them.",
       resultKey: "mergeAutomationBranch",
       options: [
         stringOption({
@@ -16148,16 +16596,36 @@ mutation MergeAutomationBranch($automationId: ID!, $branchId: ID!) {
       targetVersionId
       changes {
         id
+        kind
         group
-        label
         status
+        label
+        discardable
+        agentId
+        agentName
+        field
+        configKey
+        fromAgentId
+        toAgentId
+        conflictDescription
+        statusDescription
       }
     }
     conflicts {
       id
+      kind
       group
-      label
       status
+      label
+      discardable
+      agentId
+      agentName
+      field
+      configKey
+      fromAgentId
+      toAgentId
+      conflictDescription
+      statusDescription
     }
     applyResult {
       draftVersionId
@@ -16166,6 +16634,150 @@ mutation MergeAutomationBranch($automationId: ID!, $branchId: ID!) {
       wasRebased
     }
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "PreviewAutomationBranchMerge",
+    kind: "query",
+    inputSchema: z27.object({
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      branchId: z27.uuid("--branch-id must be a UUID.")
+    }),
+    cli: {
+      branchContext: "required",
+      name: "preview-automation-branch-merge",
+      path: ["automations", "branches", "merge-preview"],
+      description: "Explain how a branch would merge into main: one change per agent field with its status and, for conflicts, why it conflicts. Writes nothing.",
+      resultKey: "automationBranchMergePreview",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationBranchMergePreview.graphql" },
+    document: `# Explain how a branch would merge into main without writing anything.
+query PreviewAutomationBranchMerge($automationId: ID!, $branchId: ID!) {
+  automationBranchMergePreview(automationId: $automationId, branchId: $branchId) {
+    baseVersionId
+    sourceVersionId
+    targetVersionId
+    changes {
+      id
+      kind
+      group
+      status
+      label
+      discardable
+      agentId
+      agentName
+      field
+      configKey
+      fromAgentId
+      toAgentId
+      conflictDescription
+      statusDescription
+    }
+  }
+}`
+  }),
+  createOperationSpec({
+    operationName: "DiscardAutomationBranchChanges",
+    kind: "mutation",
+    inputSchema: z27.object({
+      automationId: z27.uuid("--automation-id must be a UUID."),
+      branchId: z27.uuid("--branch-id must be a UUID."),
+      changeIds: z27.array(
+        z27.string().min(1).max(
+          AUTOMATION_BRANCH_CHANGE_ID_MAX_LENGTH,
+          `--change-ids entries must be at most ${AUTOMATION_BRANCH_CHANGE_ID_MAX_LENGTH} characters.`
+        )
+      ).min(1, "--change-ids must name at least one preview change id.").max(
+        AUTOMATION_BRANCH_DISCARD_MAX_CHANGE_IDS,
+        `--change-ids can name at most ${AUTOMATION_BRANCH_DISCARD_MAX_CHANGE_IDS} preview change ids per run.`
+      ),
+      sourceVersionId: z27.uuid("--source-version-id must be a UUID."),
+      targetVersionId: z27.uuid("--target-version-id must be a UUID.")
+    }),
+    cli: {
+      branchContext: "required",
+      name: "discard-automation-branch-changes",
+      path: ["automations", "branches", "discard-changes"],
+      description: "Revert preview changes on the branch so main keeps its values. Pass the change ids plus the source and target version ids from the preview you are acting on.",
+      resultKey: "discardAutomationBranchChanges",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        }),
+        stringArrayOption({
+          inputKey: "changeIds",
+          flagName: "change-ids",
+          description: "Preview change ids to revert on the branch, for example agent:update:<agent-id>:instructions.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "sourceVersionId",
+          flagName: "source-version-id",
+          description: "sourceVersionId from the preview being acted on.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "targetVersionId",
+          flagName: "target-version-id",
+          description: "targetVersionId from the preview being acted on.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "discardAutomationBranchChanges.graphql" },
+    document: `# Revert preview changes on a branch and return the refreshed merge preview.
+mutation DiscardAutomationBranchChanges(
+  $automationId: ID!
+  $branchId: ID!
+  $changeIds: [String!]!
+  $sourceVersionId: ID!
+  $targetVersionId: ID!
+) {
+  discardAutomationBranchChanges(
+    automationId: $automationId
+    branchId: $branchId
+    changeIds: $changeIds
+    sourceVersionId: $sourceVersionId
+    targetVersionId: $targetVersionId
+  ) {
+    automationId
+    branchId
+    previousHeadVersionId
+    headVersionId
+    discardedChangeIds
+    preview {
+      baseVersionId
+      sourceVersionId
+      targetVersionId
+      changes {
+        id
+        kind
+        group
+        status
+        label
+        discardable
+        agentId
+        agentName
+        field
+        configKey
+        fromAgentId
+        toAgentId
+        conflictDescription
+        statusDescription
+      }
+    }
+  }
 }`
   }),
   createOperationSpec({
@@ -16276,7 +16888,8 @@ query GetAvailableCommands($env: AvailableCommandsEnv!) {
     operationName: "GetAvailableModels",
     kind: "query",
     inputSchema: z27.object({
-      agentId: z27.string().min(1)
+      agentId: z27.string().min(1),
+      automationId: z27.string().min(1)
     }),
     cli: {
       name: "get-available-models",
@@ -16289,13 +16902,20 @@ query GetAvailableCommands($env: AvailableCommandsEnv!) {
           flagName: "agent-id",
           description: "Agent ID.",
           required: true
+        }),
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation whose head pins the agent (required with agent-id).",
+          required: true
         })
       ]
     },
     mcp: { fileName: "availableModels.graphql" },
     document: `# Query to fetch available model definitions and pools for a specific agent
-query GetAvailableModels($agentId: String!) {
-  availableModels(agentId: $agentId) {
+# from that automation's head (agent model config resolves branch-safely).
+query GetAvailableModels($agentId: String!, $automationId: String!) {
+  availableModels(agentId: $agentId, automationId: $automationId) {
     availableModelPools {
       name
       poolId
@@ -18348,7 +18968,7 @@ ${evalRunExportSelection}
 ];
 
 // src/program.ts
-import { Command as Command3, InvalidArgumentError as InvalidArgumentError2, Option as Option3 } from "commander";
+import { Command as Command4, InvalidArgumentError as InvalidArgumentError2, Option as Option4 } from "commander";
 
 // src/api.ts
 import { randomUUID } from "node:crypto";
@@ -18682,8 +19302,110 @@ var pathwayRegressionRunResultResponseSchema = z28.object({
     workflowId: z28.string().min(1)
   })
 });
-var graphQlResponseSchema = z28.object({
-  data: z28.record(z28.string(), z28.unknown()).nullable().optional(),
+var regressionTestPathwayStatusSchema = z28.enum([
+  "new_pathway",
+  "missing_after_change",
+  "historical_path_missing_after_change",
+  "no_matching_runs",
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored"
+]);
+var regressionTestStatusSchema = z28.enum([
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored"
+]);
+var regressionTestKickoffPathwaySchema = z28.object({
+  baselineContractPathId: z28.string().min(1).nullable(),
+  baselineLabel: z28.string().nullable(),
+  candidateContractPathId: z28.string().min(1).nullable(),
+  candidateLabel: z28.string().nullable(),
+  id: z28.string().min(1),
+  pathwayKey: z28.string().min(1),
+  status: regressionTestPathwayStatusSchema
+});
+var regressionTestKickoffResponseSchema = z28.object({
+  pathways: z28.array(regressionTestKickoffPathwaySchema),
+  regressionTestId: z28.string().min(1),
+  status: regressionTestStatusSchema
+});
+var regressionTestIterationCountsSchema = z28.object({
+  errored: z28.number(),
+  failed: z28.number(),
+  passed: z28.number(),
+  total: z28.number()
+});
+var regressionTestBaselineRunSummarySchema = z28.object({
+  id: z28.string().min(1),
+  iterationCounts: regressionTestIterationCountsSchema
+});
+var regressionTestPathwaySummarySchema = z28.object({
+  baselineLabel: z28.string().nullable(),
+  baselineRuns: z28.array(regressionTestBaselineRunSummarySchema),
+  candidateLabel: z28.string().nullable(),
+  id: z28.string().min(1),
+  pathwayKey: z28.string().min(1),
+  status: regressionTestPathwayStatusSchema
+});
+var regressionTestResultResponseSchema = z28.object({
+  pathways: z28.array(regressionTestPathwaySummarySchema),
+  regressionTest: z28.object({
+    finishedAt: z28.string().nullable(),
+    id: z28.string().min(1),
+    startedAt: z28.string().nullable(),
+    status: regressionTestStatusSchema
+  })
+});
+var regressionTestBaselineStepSchema = z28.object({
+  expectedToolCall: z28.unknown().nullable(),
+  id: z28.string().min(1),
+  iterationIndex: z28.number()
+});
+var regressionTestFailedToolCallSchema = z28.object({
+  count: z28.number(),
+  observedToolCall: z28.unknown()
+});
+var regressionTestFailedIterationSchema = z28.object({
+  baselineIterationId: z28.string().min(1),
+  failedToolCalls: z28.array(regressionTestFailedToolCallSchema)
+});
+var regressionTestReplayCountsSchema = z28.object({
+  errored: z28.number(),
+  failed: z28.number(),
+  passed: z28.number()
+});
+var regressionTestBaselineRunSchema = z28.object({
+  baselineAgentRunId: z28.string().min(1),
+  baselineIterations: z28.array(regressionTestBaselineStepSchema),
+  failedIterations: z28.array(regressionTestFailedIterationSchema),
+  replayCounts: regressionTestReplayCountsSchema
+});
+var regressionTestPathwayDetailSchema = z28.object({
+  baselineLabel: z28.string().nullable(),
+  baselineRuns: z28.array(regressionTestBaselineRunSchema),
+  candidateLabel: z28.string().nullable(),
+  id: z28.string().min(1),
+  pathwayKey: z28.string().min(1),
+  status: regressionTestPathwayStatusSchema
+});
+var regressionTestPathwayResultResponseSchema = z28.object({
+  pathway: regressionTestPathwayDetailSchema,
+  regressionTest: z28.object({
+    finishedAt: z28.string().nullable(),
+    id: z28.string().min(1),
+    startedAt: z28.string().nullable(),
+    status: regressionTestStatusSchema
+  })
+});
+var graphQlResponseSchema = z28.object({
+  data: z28.record(z28.string(), z28.unknown()).nullable().optional(),
   errors: z28.array(
     z28.object({
       extensions: z28.object({
@@ -18723,6 +19445,7 @@ function getGraphQlErrorStatus(error) {
   return error.extensions?.appErrorType?.includes("not-found") ? 404 : void 0;
 }
 var apiErrorResponseSchema = z28.object({
+  code: z28.string().min(1).optional(),
   errors: z28.array(
     z28.object({
       message: z28.string().min(1)
@@ -18743,6 +19466,13 @@ function getApiErrorDetail(responseBody) {
   }
   return parsedResponse.data.errors.map((error) => error.message).join("\n");
 }
+function getApiErrorCode(responseBody) {
+  const parsedResponse = apiErrorResponseSchema.safeParse(responseBody);
+  if (!parsedResponse.success) {
+    return null;
+  }
+  return parsedResponse.data.code ?? null;
+}
 function getRetryAfterMs(response) {
   const retryAfter = response.headers.get("retry-after");
   if (!retryAfter) {
@@ -18872,12 +19602,12 @@ function applyAuthenticationHeaders({
   headers.set(OTTO_AUTHORIZATION_HEADER_NAME, `Bearer ${accessToken}`);
   headers.set("x-organization-id", organizationId);
 }
-function createMagicalApiClient({
+function createFetchJson({
   apiBaseUrl,
-  fetchFn = fetch
+  fetchFn
 }) {
   const resolveApiBaseUrl = typeof apiBaseUrl === "string" ? () => apiBaseUrl : apiBaseUrl;
-  async function fetchJson({
+  return async function fetchJson({
     accessToken,
     impersonatedOrganizationId,
     allowOttoAuthorization,
@@ -18929,13 +19659,23 @@ function createMagicalApiClient({
     });
     if (!response.ok) {
       const errorDetail = getApiErrorDetail(responseBody);
+      const apiErrorCode = getApiErrorCode(responseBody);
       throw new CliError(
         `Magical API request to ${url} failed with status ${response.status}${errorDetail ? `: ${errorDetail}` : "."}`,
-        errorOptions
+        {
+          ...errorOptions,
+          ...apiErrorCode === null ? {} : { apiErrorCode }
+        }
       );
     }
     return responseBody;
-  }
+  };
+}
+function createMagicalApiClient({
+  apiBaseUrl,
+  fetchFn = fetch
+}) {
+  const fetchJson = createFetchJson({ apiBaseUrl, fetchFn });
   return {
     async downloadFile({ outputPath, overwrite = false, url }) {
       if (!overwrite) {
@@ -19228,6 +19968,77 @@ function createMagicalApiClient({
         );
       }
       return parsedResponse.data;
+    },
+    async startAgentVersionRegressionTest({
+      accessToken,
+      agentVersionId,
+      automationVersionId,
+      impersonatedOrganizationId,
+      organizationId
+    }) {
+      const parsedResponse = regressionTestKickoffResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: `/pathway-regression/tests/automation-versions/${encodeURIComponent(
+            automationVersionId
+          )}/agent-versions/${encodeURIComponent(agentVersionId)}/run`,
+          init: {
+            method: "POST"
+          }
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Regression test kickoff payload was invalid.");
+      }
+      return parsedResponse.data;
+    },
+    async getAgentVersionRegressionTestResult({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId,
+      regressionTestId
+    }) {
+      const parsedResponse = regressionTestResultResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: `/pathway-regression/tests/${encodeURIComponent(
+            regressionTestId
+          )}`
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Regression test result payload was invalid.");
+      }
+      return parsedResponse.data;
+    },
+    async getAgentVersionRegressionTestPathway({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId,
+      regressionTestId,
+      testPathwayId
+    }) {
+      const parsedResponse = regressionTestPathwayResultResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: `/pathway-regression/tests/${encodeURIComponent(
+            regressionTestId
+          )}/pathways/${encodeURIComponent(testPathwayId)}`
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Regression test pathway payload was invalid.");
+      }
+      return parsedResponse.data;
     }
   };
 }
@@ -19454,6 +20265,18 @@ async function handleAuthLogin(dependencies, options) {
   );
 }
 
+// src/branch-merge.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertBranchMergeApplied(operationSpec, result) {
+  if (operationSpec.operationName === "MergeAutomationBranch" && (!isRecord5(result) || result["status"] !== "merged")) {
+    throw new CliError(
+      isRecord5(result) && result["status"] === "conflict" ? "Merge not applied. Discard the conflicting changes with `mgcl automations branches discard-changes` (main keeps its values) or edit the branch to match main, then rerun this merge command." : "Merge not applied. Review the merge output, resolve any conflicts, then merge again."
+    );
+  }
+}
+
 // src/capture-commands.ts
 import { Command, Option } from "commander";
 
@@ -19746,7 +20569,7 @@ async function pollCaptureRecording({
   onStatus,
   recordingId,
   signal,
-  sleep: sleep2 = async (delayMs) => {
+  sleep: sleep3 = async (delayMs) => {
     await defaultSleep(delayMs, signal);
   }
 }) {
@@ -19772,7 +20595,7 @@ async function pollCaptureRecording({
         throw error;
       }
       onRetry?.(error, retryDelay);
-      await sleep2(retryDelay);
+      await sleep3(retryDelay);
       return await pollNext(state);
     }
     const status = statusResult.value;
@@ -19787,7 +20610,7 @@ async function pollCaptureRecording({
     if (TERMINAL_STATUSES.has(status.status)) {
       return status;
     }
-    await sleep2(DEFAULT_POLL_INTERVAL_MS);
+    await sleep3(DEFAULT_POLL_INTERVAL_MS);
     return await pollNext({
       effectiveDeadlineMs,
       hasObservedRecording: true
@@ -20053,10 +20876,10 @@ async function finishExport({
 async function pollExport({
   executeOperation,
   exportId,
-  sleep: sleep2
+  sleep: sleep3
 }) {
   for (; ; ) {
-    await sleep2(EXPORT_POLL_INTERVAL_MS);
+    await sleep3(EXPORT_POLL_INTERVAL_MS);
     const result = parseApiResult(
       // eslint-disable-next-line no-await-in-loop -- do not overlap signed-export status requests
       await executeOperation("GetEvalRunExport", { exportId }),
@@ -20476,6 +21299,267 @@ function isExpiredAccessTokenClaims(claims) {
   return claims.exp * 1e3 <= Date.now();
 }
 
+// src/regression-commands.ts
+import { setTimeout as sleep } from "node:timers/promises";
+import { Command as Command2, Option as Option2 } from "commander";
+var REGRESSION_TEST_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored"
+]);
+var REGRESSION_TEST_POLL_INTERVAL_MS = 5e3;
+var REGRESSION_TEST_KICKOFF_RETRY_DELAY_MS = 5e3;
+var REGRESSION_TEST_RETRYABLE_KICKOFF_ERROR_CODE = "PATHWAY_CONTRACT_NOT_READY";
+function isRetryableRegressionTestKickoffError(error) {
+  return error instanceof CliError && error.statusCode === 409 && error.apiErrorCode === REGRESSION_TEST_RETRYABLE_KICKOFF_ERROR_CODE;
+}
+function summarizeRegressionTestResult(result) {
+  return {
+    regressionTestId: result.regressionTest.id,
+    status: result.regressionTest.status,
+    startedAt: result.regressionTest.startedAt,
+    finishedAt: result.regressionTest.finishedAt,
+    pathways: result.pathways.map((pathway) => ({
+      id: pathway.id,
+      pathwayKey: pathway.pathwayKey,
+      baselineLabel: pathway.baselineLabel,
+      candidateLabel: pathway.candidateLabel,
+      status: pathway.status,
+      baselineRuns: pathway.baselineRuns.map((run) => ({
+        id: run.id,
+        iterationCounts: run.iterationCounts
+      }))
+    }))
+  };
+}
+function summarizeRegressionTestPathway(result) {
+  return {
+    regressionTestId: result.regressionTest.id,
+    status: result.regressionTest.status,
+    pathway: {
+      id: result.pathway.id,
+      pathwayKey: result.pathway.pathwayKey,
+      baselineLabel: result.pathway.baselineLabel,
+      candidateLabel: result.pathway.candidateLabel,
+      status: result.pathway.status,
+      baselineRuns: result.pathway.baselineRuns.map((run) => ({
+        baselineAgentRunId: run.baselineAgentRunId,
+        replayCounts: run.replayCounts,
+        baselineIterationCount: run.baselineIterations.length,
+        failedIterations: run.failedIterations.map((fi) => ({
+          baselineIterationId: fi.baselineIterationId,
+          failedToolCalls: fi.failedToolCalls.map((ftc) => ({
+            observedToolCall: ftc.observedToolCall,
+            count: ftc.count
+          }))
+        }))
+      }))
+    }
+  };
+}
+async function startRegressionTestWithRetry({
+  dependencies,
+  input,
+  startRegressionTest
+}) {
+  for (; ; ) {
+    const result = await fromThrowable(
+      startRegressionTest.bind(void 0, input),
+      "regression-test-kickoff-failed"
+    );
+    if (!isErr(result)) {
+      return result.value;
+    }
+    if (!isRetryableRegressionTestKickoffError(result.error.cause)) {
+      throw result.error.cause;
+    }
+    dependencies.io.info("Contract generation in progress, retrying...");
+    await sleep(REGRESSION_TEST_KICKOFF_RETRY_DELAY_MS);
+  }
+}
+async function pollRegressionTestResult({
+  dependencies,
+  getRegressionTestResult,
+  input,
+  regressionTestId
+}) {
+  for (; ; ) {
+    await sleep(REGRESSION_TEST_POLL_INTERVAL_MS);
+    const result = await getRegressionTestResult({
+      ...input,
+      regressionTestId
+    });
+    if (REGRESSION_TEST_TERMINAL_STATUSES.has(result.regressionTest.status)) {
+      return result;
+    }
+    dependencies.io.info(
+      `Regression test ${regressionTestId}: ${result.regressionTest.status}...`
+    );
+  }
+}
+async function handleRegressionRunCommand({
+  dependencies,
+  helpers,
+  options
+}) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await helpers.withSelectedOrganizationAndAccessToken({
+    dependencies,
+    options
+  });
+  const startAgentVersionRegressionTest = helpers.requireApiClientMethod(
+    dependencies.apiClient,
+    "startAgentVersionRegressionTest"
+  );
+  const getAgentVersionRegressionTestResult = helpers.requireApiClientMethod(
+    dependencies.apiClient,
+    "getAgentVersionRegressionTestResult"
+  );
+  const authParams = {
+    accessToken,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  };
+  const kickoffResult = await startRegressionTestWithRetry({
+    dependencies,
+    input: {
+      ...authParams,
+      agentVersionId: options.agentVersion,
+      automationVersionId: options.automationVersion
+    },
+    startRegressionTest: startAgentVersionRegressionTest
+  });
+  const { regressionTestId } = kickoffResult;
+  dependencies.io.info(`Regression test started: ${regressionTestId}`);
+  const result = await pollRegressionTestResult({
+    dependencies,
+    getRegressionTestResult: getAgentVersionRegressionTestResult,
+    input: authParams,
+    regressionTestId
+  });
+  await helpers.saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  helpers.writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizeRegressionTestResult(result)
+  });
+}
+async function handleRegressionShowCommand({
+  dependencies,
+  helpers,
+  options
+}) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await helpers.withSelectedOrganizationAndAccessToken({
+    dependencies,
+    options
+  });
+  const authParams = {
+    accessToken,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  };
+  await helpers.saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  if (options.pathway) {
+    const getAgentVersionRegressionTestPathway = helpers.requireApiClientMethod(
+      dependencies.apiClient,
+      "getAgentVersionRegressionTestPathway"
+    );
+    const result2 = await getAgentVersionRegressionTestPathway({
+      ...authParams,
+      regressionTestId: options.testId,
+      testPathwayId: options.pathway
+    });
+    helpers.writeCommandOutput({
+      dependencies,
+      json: options.json,
+      result: options.json ? result2 : summarizeRegressionTestPathway(result2)
+    });
+    return;
+  }
+  const getAgentVersionRegressionTestResult = helpers.requireApiClientMethod(
+    dependencies.apiClient,
+    "getAgentVersionRegressionTestResult"
+  );
+  const result = await getAgentVersionRegressionTestResult({
+    ...authParams,
+    regressionTestId: options.testId
+  });
+  helpers.writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizeRegressionTestResult(result)
+  });
+}
+function addRegressionCommands({
+  dependencies,
+  helpers,
+  program: program2
+}) {
+  const regressionCommand = configureCommandPresentation(
+    new Command2("regression").description(
+      "Run and inspect agent version regression tests."
+    )
+  ).helpGroup("Workspace:").addHelpText(
+    "after",
+    `
+${formatExamples("Examples", [
+      "mgcl regression run --automation-version <id> --agent-version <id>",
+      "mgcl regression show <testId>",
+      "mgcl regression show <testId> --pathway <pathwayId>"
+    ])}`
+  );
+  regressionCommand.command("run").description(
+    "Start a regression test, poll until complete, and return the summary."
+  ).addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--automation-version <id>",
+      "Automation version to test against."
+    ).helpGroup("Regression options:").makeOptionMandatory(true)
+  ).addOption(
+    new Option2("--agent-version <id>", "Agent version to test.").helpGroup("Regression options:").makeOptionMandatory(true)
+  ).action(async function() {
+    await handleRegressionRunCommand({
+      dependencies,
+      helpers,
+      options: this.optsWithGlobals()
+    });
+  });
+  regressionCommand.command("show <testId>").description("Show regression test results.").addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--pathway <pathwayId>",
+      "Show detail for a specific pathway."
+    ).helpGroup("Regression options:")
+  ).action(async function(testId) {
+    await handleRegressionShowCommand({
+      dependencies,
+      helpers,
+      options: {
+        ...this.optsWithGlobals(),
+        testId
+      }
+    });
+  });
+  program2.addCommand(regressionCommand);
+}
+
 // src/self-update.ts
 import { spawn as spawn2 } from "node:child_process";
 import fs2 from "node:fs";
@@ -20640,7 +21724,7 @@ async function selfUpdateInstalledCli({
 }
 
 // src/settings-command.ts
-import { Command as Command2, InvalidArgumentError, Option as Option2 } from "commander";
+import { Command as Command3, InvalidArgumentError, Option as Option3 } from "commander";
 function writeJsonOutput2(io, value) {
   io.info(JSON.stringify(value, null, 2));
 }
@@ -20718,7 +21802,7 @@ async function handleSettingsEnvBaseUrl(dependencies, rawBaseUrl, options) {
 }
 function createSettingsCommand(dependencies) {
   const settingsCommand = configureCommandPresentation(
-    new Command2("settings").description("Manage persisted CLI settings.")
+    new Command3("settings").description("Manage persisted CLI settings.")
   ).helpGroup("Workspace:").addHelpText(
     "after",
     `
@@ -20728,7 +21812,7 @@ ${formatExamples("Examples", [
     ])}`
   );
   const settingsEnvCommand = settingsCommand.command("env").description("Manage persisted environment overrides.");
-  settingsEnvCommand.command("base-url [url]").description("Set or clear the persisted Magical API base URL override.").addOption(new Option2("--reset", "Clear the persisted base URL override.")).action(async function(baseUrl) {
+  settingsEnvCommand.command("base-url [url]").description("Set or clear the persisted Magical API base URL override.").addOption(new Option3("--reset", "Clear the persisted base URL override.")).action(async function(baseUrl) {
     await handleSettingsEnvBaseUrl(
       dependencies,
       baseUrl,
@@ -21556,7 +22640,7 @@ var accessTokenClaimsSchema = z34.object({
 });
 function createWorkosAuthClient({
   fetchFn = fetch,
-  sleep: sleep2 = async (milliseconds) => {
+  sleep: sleep3 = async (milliseconds) => {
     await new Promise((resolve) => {
       setTimeout(resolve, milliseconds);
     });
@@ -21650,12 +22734,12 @@ function createWorkosAuthClient({
           );
         }
         if (parsedError.data.error === "authorization_pending") {
-          await sleep2(nextIntervalMilliseconds);
+          await sleep3(nextIntervalMilliseconds);
           return poll(nextIntervalMilliseconds);
         }
         if (parsedError.data.error === "slow_down") {
           const slowedIntervalMilliseconds = nextIntervalMilliseconds + 5e3;
-          await sleep2(slowedIntervalMilliseconds);
+          await sleep3(slowedIntervalMilliseconds);
           return poll(slowedIntervalMilliseconds);
         }
         throw new CliError(
@@ -21739,7 +22823,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
 function createCliCommanderOption(optionSpec, helpGroup) {
   const optionFlags = optionSpec.valueType === "boolean" ? `--${optionSpec.flagName}` : `--${optionSpec.flagName} <value>`;
   const optionDescription = optionSpec.valueHint ? `${optionSpec.description} (${optionSpec.valueHint})` : optionSpec.description;
-  const nextOption = new Option3(optionFlags, optionDescription).helpGroup(
+  const nextOption = new Option4(optionFlags, optionDescription).helpGroup(
     helpGroup
   );
   if (optionSpec.valueType === "boolean") {
@@ -21759,7 +22843,7 @@ function parsePositiveIntegerOption(rawValue) {
   }
   return parsedValue;
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveOrganizationBySelector({
@@ -21836,7 +22920,7 @@ function parseOperationVariables(operationSpec, variables) {
       parsedVariables.error.issues[0]?.message ?? "Invalid command input."
     );
   }
-  if (!isRecord5(parsedVariables.data)) {
+  if (!isRecord6(parsedVariables.data)) {
     throw new CliError("Invalid command input.");
   }
   return parsedVariables.data;
@@ -21934,13 +23018,17 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     ...state,
     lastUsedOrgId: organization.id
   });
+  const humanReadableFormatter = getBranchMergeFormatter(
+    operationSpec.operationName
+  );
   writeCommandOutput({
     dependencies,
+    ...humanReadableFormatter ? { humanReadableFormatter } : {},
     json: commandOptions.json,
     result
   });
   assertBranchMergeApplied(operationSpec, result);
-  if (operationSpec.operationName === "ViewAutomationReview" && commandOptions["open"] && isRecord5(result) && typeof result["reportUrl"] === "string") {
+  if (operationSpec.operationName === "ViewAutomationReview" && commandOptions["open"] && isRecord6(result) && typeof result["reportUrl"] === "string") {
     await dependencies.openExternalUrl(result["reportUrl"]).catch((error) => {
       dependencies.io.error(
         `Warning: Failed to open the automation review in the default browser: ${getErrorMessage(error)}`
@@ -21948,13 +23036,6 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     });
   }
 }
-function assertBranchMergeApplied(operationSpec, result) {
-  if (operationSpec.operationName === "MergeAutomationBranch" && (!isRecord5(result) || result["status"] !== "merged")) {
-    throw new CliError(
-      "Merge not applied. Review the merge output, resolve any conflicts, then merge again."
-    );
-  }
-}
 function getOperation(operationName) {
   const operationSpec = operationSpecs.find(
     (candidate) => candidate.operationName === operationName
@@ -22127,12 +23208,12 @@ function addSkillsWorkingCopyCommands({
   skillsCommand
 }) {
   skillsCommand.command("pull <skill>").description("Download a root-level skill into ./skills/<skill-name>.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3(
+    new Option4(
       "--force",
       "Replace existing files or local edits with the remote bundle."
     )
@@ -22151,7 +23232,7 @@ ${formatExamples("Examples", [
     );
   });
   skillsCommand.command("diff <skill>").description("Preview local skill changes against the pulled bundle.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
@@ -22170,12 +23251,12 @@ ${formatExamples("Examples", [
     );
   });
   skillsCommand.command("push <skill>").description("Atomically push local changes for one root-level skill.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3("--message <message>", "Commit message for the skill update.")
+    new Option4("--message <message>", "Commit message for the skill update.")
   ).addHelpText(
     "after",
     `
@@ -22216,6 +23297,7 @@ async function withSelectedOrganizationAndAccessToken({
 }
 function writeCommandOutput({
   dependencies,
+  humanReadableFormatter = formatHumanReadableOutput,
   json,
   result
 }) {
@@ -22223,7 +23305,7 @@ function writeCommandOutput({
     writeJsonOutput3(dependencies.io, result);
     return;
   }
-  dependencies.io.info(formatHumanReadableOutput(result));
+  dependencies.io.info(humanReadableFormatter(result));
 }
 async function handleNangoIntegrationsListCommand(dependencies, options) {
   const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
@@ -22607,7 +23689,7 @@ async function retryCaptureRequest({
     throw error;
   }
   onRetry(error, retryDelay);
-  await sleep(retryDelay, void 0, { signal }).catch(
+  await sleep2(retryDelay, void 0, { signal }).catch(
     (sleepError) => {
       throw new CliError("Capture wait interrupted.", { cause: sleepError });
     }
@@ -22857,7 +23939,7 @@ function configureOperationalCommand(command, dependencies, operationSpec) {
   command.description(operationSpec.cli.description);
   if (operationSpec.scope !== "global") {
     command.addOption(
-      new Option3(
+      new Option4(
         "--org <org>",
         "Organization ID or exact organization name to use."
       ).helpGroup("Shared options:")
@@ -22938,14 +24020,14 @@ function createDefaultDependencies() {
 }
 function buildProgram(dependencies) {
   const program2 = configureCommandPresentation(
-    new Command3().name("mgcl").description("Run Magical operations from the command line.")
-  ).addOption(new Option3("--json", "Render JSON output.")).addOption(
-    new Option3(
+    new Command4().name("mgcl").description("Run Magical operations from the command line.")
+  ).addOption(new Option4("--json", "Render JSON output.")).addOption(
+    new Option4(
       "--branch-id <id>",
       'Target a supported automation command at one branch; omit it to target main. "Branch-aware commands" below lists the commands that accept it.'
     )
   ).version(CLI_VERSION, "--version", `Display mgcl version (${CLI_VERSION}).`).addOption(
-    new Option3(
+    new Option4(
       "--update",
       "Update mgcl to the latest published npm release."
     )
@@ -22971,7 +24053,7 @@ function buildProgram(dependencies) {
     this.outputHelp();
   });
   const authCommand = configureCommandPresentation(
-    new Command3("auth").description("Manage CLI authentication.")
+    new Command4("auth").description("Manage CLI authentication.")
   ).helpGroup("Workspace:").addHelpText(
     "after",
     `
@@ -22986,7 +24068,7 @@ ${formatExamples("Examples", ["mgcl auth login", "mgcl auth logout"])}`
   program2.addCommand(authCommand);
   program2.addCommand(createSettingsCommand(dependencies));
   const orgCommand = configureCommandPresentation(
-    new Command3("org").description("Manage organization selection.")
+    new Command4("org").description("Manage organization selection.")
   ).helpGroup("Workspace:").addHelpText(
     "after",
     `
@@ -23007,7 +24089,7 @@ ${formatExamples("Examples", [
   });
   program2.addCommand(orgCommand);
   const pathwayRegressionCommand = configureCommandPresentation(
-    new Command3("pathway-regression").description(
+    new Command4("pathway-regression").description(
       "Preview, start, and inspect pathway regression runs."
     )
   ).helpGroup("Workspace:").addHelpText(
@@ -23021,20 +24103,20 @@ ${formatExamples("Examples", [
     ])}`
   );
   const addPathwayRegressionAgentVersionOptions = (command) => command.addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3(
+    new Option4(
       "--automation-version-id <id>",
       "Automation version to test against."
     ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
   ).addOption(
-    new Option3("--agent-version-id <id>", "Agent version to test.").helpGroup("Pathway regression options:").makeOptionMandatory(true)
+    new Option4("--agent-version-id <id>", "Agent version to test.").helpGroup("Pathway regression options:").makeOptionMandatory(true)
   );
   const addPathwayRegressionPreviewOptions = (command) => addPathwayRegressionAgentVersionOptions(command).addOption(
-    new Option3(
+    new Option4(
       "--runs-per-path <count>",
       "Number of historical runs to use per pathway. Defaults to the service value."
     ).helpGroup("Pathway regression options:").argParser(parsePositiveIntegerOption)
@@ -23056,12 +24138,12 @@ ${formatExamples("Examples", [
     );
   });
   pathwayRegressionCommand.command("results").description("Read a pathway regression run result.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3(
+    new Option4(
       "--regression-run-id <id>",
       "Pathway regression run ID to inspect."
     ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
@@ -23072,12 +24154,12 @@ ${formatExamples("Examples", [
     );
   });
   pathwayRegressionCommand.command("check-results").description("Read detailed check attempts for one replay iteration.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3(
+    new Option4(
       "--regression-replay-iteration-id <id>",
       "Pathway regression replay iteration ID to inspect."
     ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
@@ -23088,19 +24170,29 @@ ${formatExamples("Examples", [
     );
   });
   program2.addCommand(pathwayRegressionCommand);
+  addRegressionCommands({
+    dependencies,
+    helpers: {
+      requireApiClientMethod,
+      saveLastUsedOrganization,
+      withSelectedOrganizationAndAccessToken,
+      writeCommandOutput
+    },
+    program: program2
+  });
   const pathwaysCommand = configureCommandPresentation(
-    new Command3("pathways").description("Inspect pathways.")
+    new Command4("pathways").description("Inspect pathways.")
   ).helpGroup("Workspace:");
   const pathwaySignaturesCommand = configureCommandPresentation(
-    new Command3("signatures").description("Inspect agent-run signatures.")
+    new Command4("signatures").description("Inspect agent-run signatures.")
   );
   pathwaySignaturesCommand.command("get").description("Read an agent-run pathway signature.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3("--agent-run-id <id>", "Agent run ID to inspect.").helpGroup("Pathway signature options:").makeOptionMandatory(true)
+    new Option4("--agent-run-id <id>", "Agent run ID to inspect.").helpGroup("Pathway signature options:").makeOptionMandatory(true)
   ).action(async function() {
     await handlePathwaySignatureGetCommand(
       dependencies,
@@ -23110,7 +24202,7 @@ ${formatExamples("Examples", [
   pathwaysCommand.addCommand(pathwaySignaturesCommand);
   program2.addCommand(pathwaysCommand);
   const nangoCommand = configureCommandPresentation(
-    new Command3("nango").description(
+    new Command4("nango").description(
       "Inspect Nango integrations and org-scoped authentications."
     )
   ).helpGroup("Workspace:").addHelpText(
@@ -23122,10 +24214,10 @@ ${formatExamples("Examples", [
     ])}`
   );
   const nangoIntegrationsCommand = configureCommandPresentation(
-    new Command3("integrations").description("Work with Nango integrations.")
+    new Command4("integrations").description("Work with Nango integrations.")
   );
   nangoIntegrationsCommand.command("list").description("List Nango integrations available in the current workspace.").addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
@@ -23137,22 +24229,22 @@ ${formatExamples("Examples", [
   });
   nangoCommand.addCommand(nangoIntegrationsCommand);
   const nangoAuthsCommand = configureCommandPresentation(
-    new Command3("auths").alias("authentications").description("Work with org-scoped Nango authentications.")
+    new Command4("auths").alias("authentications").description("Work with org-scoped Nango authentications.")
   );
   nangoAuthsCommand.command("list").description(
     "List org-scoped Nango authentications and their connection IDs."
   ).addOption(
-    new Option3(
+    new Option4(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
   ).addOption(
-    new Option3(
+    new Option4(
       "--integration <integration>",
       "Optional integration key to filter Nango authentications."
     )
   ).addOption(
-    new Option3(
+    new Option4(
       "--connection-id <connectionId>",
       "Optional connection ID to filter Nango authentications."
     )
@@ -23170,7 +24262,7 @@ ${formatExamples("Examples", [
   nangoCommand.addCommand(nangoAuthsCommand);
   program2.addCommand(nangoCommand);
   const updateCommand = configureCommandPresentation(
-    new Command3("update").description(
+    new Command4("update").description(
       "Update mgcl to the latest published npm release."
     )
   ).helpGroup("Workspace:").addHelpText(