@getmagical/cli 0.2.6 → 0.2.8

package/dist/index.js

@@ -13882,9 +13882,16 @@ function normalizeRepoPath(path9) {
   return path9.replaceAll(/\/+$/gu, "");
 }
 var skillPathPattern = /^(?:skills\/.+|automations\/[^/]+\/skills\/.+|automations\/[^/]+\/agents\/[^/]+\/skills\/.+)$/u;
+var skillRootPathPattern = /^(?:skills\/[^/]+|automations\/[^/]+\/skills\/[^/]+|automations\/[^/]+\/agents\/[^/]+\/skills\/[^/]+)$/u;
 var repoPathSchema = z21.string().min(1).transform(normalizeRepoPath).refine(isNormalizedRepoPath, {
   message: "Path must be a normalized repository-relative path."
 });
+var registeredSkillPathSchema = repoPathSchema.refine((path9) => skillPathPattern.test(path9), {
+  message: "Skill paths must be under root, automation, or automation-agent skills."
+});
+var registeredSkillRootPathSchema = registeredSkillPathSchema.refine((path9) => skillRootPathPattern.test(path9) && !path9.endsWith("/SKILL.md"), {
+  message: "Registered skill paths must identify a skill root directory."
+});
 var knowledgeBasePluginPermissionSchema = z21.object({
   path: repoPathSchema.refine(getIsKnowledgeBaseAssetPathAllowed, {
     message: "Knowledge Base paths must be under org, automation, or automation-agent assets."
@@ -13900,9 +13907,7 @@ var memoryConfigSchema = z21.object({
 }).strict().describe("Configuration for the memory runtime plugin.");
 var skillsConfigSchema = z21.object({
   enabled: z21.boolean().default(false).describe("Explicit rollout switch for the skills runtime plugin."),
-  registeredSkills: z21.array(repoPathSchema.refine((path9) => skillPathPattern.test(path9), {
-    message: "Skill paths must be under root, automation, or automation-agent skills."
-  })).default(() => []).describe("Repository skill root paths available to the skills plugin."),
+  registeredSkills: z21.array(registeredSkillPathSchema).default(() => []).describe("Repository skill root paths available to the skills plugin."),
   canEdit: z21.boolean().default(false).describe("Allows the skills runtime plugin to edit repo skills under the root skills folder.")
 }).describe("Configuration for the skills runtime plugin.");
 var agentPluginsConfigSchema = z21.object({
@@ -14270,7 +14275,8 @@ var automationRunConfigBaseSchema = z24.object({
   resolvedRunSettings: automationRunResolvedRunSettingsSchema.optional().describe("Canonical run settings snapshotted onto the automation run at creation time. Present only for runSettings mode; legacyConfig mode intentionally resolves runtime settings from each current agent config instead of storing a misleading snapshot."),
   queueResourcePools: resourcePoolsSchema.optional().describe("Canonical deduped resource-pool requirements snapshotted for queue and slot assignment. Present on new runs so assignment does not recompute requirements from mutable agent config."),
   credentialVariableResourcePools: resourcePoolsSchema.optional().describe("Additional resource pools selected through credential-valued automation variables. These are additive queue requirements and do not change whether the run uses runSettings or legacyConfig as its runtime settings source."),
-  resolvedRunSettingsSource: z24.enum(["runSettings", "legacyConfig"]).optional().describe("Runtime mode decided at run creation. runSettings means resolvedRunSettings is canonical for browser/session/resource-pool behaviour; legacyConfig means runtime consumers must use current agent legacy config fields.")
+  resolvedRunSettingsSource: z24.enum(["runSettings", "legacyConfig"]).optional().describe("Runtime mode decided at run creation. runSettings means resolvedRunSettings is canonical for browser/session/resource-pool behaviour; legacyConfig means runtime consumers must use current agent legacy config fields."),
+  automationVersionPinned: z24.literal(true).optional().describe("Infrastructure-owned marker set when the run was explicitly pinned to an automation version (e.g. a branch head draft run). Draft-scoped prompt rendering must keep the pinned agent version instead of re-resolving the latest draft instructions.")
 });
 var automationRunConfigSchema = automationRunConfigBaseSchema.superRefine((config, ctx) => {
   if (config.networkTrafficCaptureExplicitlyDisabled === true && config.networkTrafficCapture !== void 0) {
@@ -14283,6 +14289,7 @@ var automationRunConfigSchema = automationRunConfigBaseSchema.superRefine((confi
 });
 var automationRunStartConfigSchema = automationRunConfigBaseSchema.omit({
   allowPointOfNoReturnOverride: true,
+  automationVersionPinned: true,
   credentialVariableResourcePools: true,
   implicitNetworkTrafficRecordingDecision: true,
   networkTrafficCapture: true,
@@ -14391,6 +14398,8 @@ function createOperationSpec(spec) {
 }
 
 // ../mcp-registry/src/operation-specs.ts
+var AUTOMATION_BRANCH_NAME_PATTERN = /^[\da-z]+(?:-[\da-z]+)*$/u;
+var AUTOMATION_BRANCH_NAME_MESSAGE = 'Branch name must use lowercase letters or numbers separated by single dashes (for example, "release-2").';
 function stringOption({
   clientOnly = false,
   description,
@@ -15573,6 +15582,228 @@ query GetAutomations($ids: [ID!]!) {
       }
     }
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "ViewAutomationReview",
+    kind: "query",
+    inputSchema: z25.object({
+      automationId: z25.string().min(1)
+    }),
+    cli: {
+      name: "view-automation-review",
+      path: ["automations", "view-review"],
+      description: "View the successful review for the current automation version.",
+      resultKey: "automationReviewReport",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        }),
+        booleanOption({
+          clientOnly: true,
+          inputKey: "open",
+          flagName: "open",
+          description: "Open the signed report URL in the default browser."
+        })
+      ]
+    },
+    mcp: { fileName: "automationReviewReport.graphql" },
+    document: `# View the successful review for the exact current automation version
+query ViewAutomationReview($automationId: ID!) {
+  automationReviewReport(automationId: $automationId) {
+    reportUrl
+    html
+  }
+}`
+  }),
+  createOperationSpec({
+    operationName: "ListAutomationBranches",
+    kind: "query",
+    inputSchema: z25.object({
+      automationId: z25.string().min(1)
+    }),
+    cli: {
+      name: "list-automation-branches",
+      path: ["automations", "branches", "list"],
+      description: "List active branches for an automation.",
+      resultKey: "automationBranches",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationBranches.graphql" },
+    document: `# List active automation branches. Deleted branches are excluded.
+query ListAutomationBranches($automationId: ID!) {
+  automationBranches(automationId: $automationId) {
+    branchId
+    automationId
+    name
+    headVersionId
+    forkedFromBranchId
+    forkedFromVersionId
+    createdAt
+    updatedAt
+  }
+}`
+  }),
+  createOperationSpec({
+    operationName: "CreateAutomationBranch",
+    kind: "mutation",
+    inputSchema: z25.object({
+      automationId: z25.string().min(1),
+      name: z25.string().regex(AUTOMATION_BRANCH_NAME_PATTERN, AUTOMATION_BRANCH_NAME_MESSAGE),
+      sourceBranchId: z25.string().min(1).optional(),
+      sourceVersionId: z25.string().min(1).optional()
+    }),
+    cli: {
+      name: "create-automation-branch",
+      path: ["automations", "branches", "create"],
+      description: "Create an automation branch. The source defaults to the current main head.",
+      resultKey: "createAutomationBranch",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        }),
+        stringOption({
+          inputKey: "name",
+          flagName: "name",
+          description: 'Lowercase branch name with single dashes between words or numbers (for example, "release-2").',
+          required: true
+        }),
+        stringOption({
+          inputKey: "sourceBranchId",
+          flagName: "source-branch-id",
+          description: "Optional source branch ID. Omit to branch from main."
+        }),
+        stringOption({
+          inputKey: "sourceVersionId",
+          flagName: "source-version-id",
+          description: "Optional version in the selected source history. Omit to use its head."
+        })
+      ]
+    },
+    mcp: { fileName: "createAutomationBranch.graphql" },
+    document: `# Create an automation branch from main or another branch.
+mutation CreateAutomationBranch(
+  $automationId: ID!
+  $name: String!
+  $sourceBranchId: ID
+  $sourceVersionId: ID
+) {
+  createAutomationBranch(
+    automationId: $automationId
+    name: $name
+    sourceBranchId: $sourceBranchId
+    sourceVersionId: $sourceVersionId
+  ) {
+    branchId
+    automationId
+    name
+    headVersionId
+    forkedFromBranchId
+    forkedFromVersionId
+    createdAt
+    updatedAt
+  }
+}`
+  }),
+  createOperationSpec({
+    operationName: "GetAutomationBranch",
+    kind: "query",
+    inputSchema: z25.object({
+      automationId: z25.string().min(1),
+      branchId: z25.string().min(1)
+    }),
+    cli: {
+      branchContext: "required",
+      name: "get-automation-branch",
+      path: ["automations", "branches", "get"],
+      description: "Get the hydrated snapshot at an automation branch head without authentication secrets.",
+      resultKey: "automationBranchHead",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "automationBranchHead.graphql" },
+    document: `# Get the hydrated snapshot at an active branch head. Authentication secrets are excluded.
+query GetAutomationBranch($automationId: ID!, $branchId: ID!) {
+  automationBranchHead(automationId: $automationId, branchId: $branchId) {
+    branchId
+    headVersionId
+    automation
+  }
+}`
+  }),
+  createOperationSpec({
+    operationName: "MergeAutomationBranch",
+    kind: "mutation",
+    inputSchema: z25.object({
+      automationId: z25.string().min(1),
+      branchId: z25.string().min(1)
+    }),
+    cli: {
+      branchContext: "required",
+      name: "merge-automation-branch",
+      path: ["automations", "branches", "merge"],
+      description: "Preview and merge a branch into main when every change is conflict-free.",
+      resultKey: "mergeAutomationBranch",
+      options: [
+        stringOption({
+          inputKey: "automationId",
+          flagName: "automation-id",
+          description: "Automation ID.",
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "mergeAutomationBranch.graphql" },
+    document: `# Preview a branch merge and apply it only when there are no conflicts.
+mutation MergeAutomationBranch($automationId: ID!, $branchId: ID!) {
+  mergeAutomationBranch(automationId: $automationId, branchId: $branchId) {
+    automationId
+    branchId
+    status
+    sourceBranchDeleted
+    preview {
+      baseVersionId
+      sourceVersionId
+      targetVersionId
+      changes {
+        id
+        group
+        label
+        status
+      }
+    }
+    conflicts {
+      id
+      group
+      label
+      status
+    }
+    applyResult {
+      draftVersionId
+      lastSavedAt
+      publishedVersionId
+      wasRebased
+    }
+  }
 }`
   }),
   createOperationSpec({
@@ -15827,9 +16058,11 @@ query GetAutomationWorkbenchCredentials {
     operationName: "GetAutomationWorkbenchDiagnostics",
     kind: "query",
     inputSchema: z25.object({
-      draftAutomationId: z25.string().min(1)
+      draftAutomationId: z25.string().min(1),
+      branchId: z25.string().min(1).optional()
     }),
     cli: {
+      branchContext: "optional",
       name: "get-automation-workbench-diagnostics",
       path: ["workbench", "diagnostics"],
       description: "Fetch a compact draft automation graph plus workbench diagnostics.",
@@ -15845,8 +16078,10 @@ query GetAutomationWorkbenchCredentials {
     },
     mcp: { fileName: "automationWorkbenchDiagnostics.graphql" },
     document: `# Query automation workbench diagnostics for a draft automation.
-query GetAutomationWorkbenchDiagnostics($draftAutomationId: ID!) {
-  automationWorkbenchDiagnostics(draftAutomationId: $draftAutomationId) {
+query GetAutomationWorkbenchDiagnostics($draftAutomationId: ID!, $branchId: ID) {
+  automationWorkbenchDiagnostics(draftAutomationId: $draftAutomationId, branchId: $branchId) {
+    branchId
+    headVersionId
     summary {
       draftAutomationId
       name
@@ -16191,10 +16426,19 @@ query GetAutomationWorkbenchAwaitRunCompletion(
     inputSchema: z25.object({
       automationRunId: z25.string().min(1),
       draftAutomationId: z25.string().min(1).optional(),
+      branchId: z25.string().min(1).optional(),
       minConfidence: z25.number().min(0).max(1).optional(),
       includeSensitive: z25.boolean().optional()
+    }).superRefine((input, ctx) => {
+      if (input.branchId && !input.draftAutomationId) {
+        ctx.addIssue({
+          code: z25.ZodIssueCode.custom,
+          message: "--branch-id requires --draft-automation-id."
+        });
+      }
     }),
     cli: {
+      branchContext: "optional",
       name: "get-automation-workbench-schema-suggestions",
       path: ["workbench", "schema-suggestions"],
       description: "Heuristic suggestions for schema fields the agent observed on browser pages but were not declared in the input schema.",
@@ -16229,15 +16473,19 @@ query GetAutomationWorkbenchAwaitRunCompletion(
 query GetAutomationWorkbenchSchemaSuggestions(
   $automationRunId: ID!
   $draftAutomationId: ID
+  $branchId: ID
   $minConfidence: Float
   $includeSensitive: Boolean
 ) {
   automationWorkbenchSchemaSuggestions(
     automationRunId: $automationRunId
     draftAutomationId: $draftAutomationId
+    branchId: $branchId
     minConfidence: $minConfidence
     includeSensitive: $includeSensitive
   ) {
+    branchId
+    headVersionId
     kind
     fieldName
     fieldLabel
@@ -16676,6 +16924,7 @@ mutation ResumeAutomationRun($automationRunId: ID!, $message: String) {
     kind: "mutation",
     inputSchema: z25.object({
       draftAutomationId: z25.string().min(1),
+      branchId: z25.string().min(1).optional(),
       agentId: z25.string().min(1),
       idempotencyKey: z25.string().min(1),
       input: z25.unknown().optional(),
@@ -16685,6 +16934,7 @@ mutation ResumeAutomationRun($automationRunId: ID!, $message: String) {
       consistencyCheckCount: z25.number().int().optional()
     }),
     cli: {
+      branchContext: "optional",
       name: "run-draft-automation",
       path: ["automations", "run-draft"],
       description: "Run a draft automation with an explicit trigger agent.",
@@ -16740,6 +16990,7 @@ mutation ResumeAutomationRun($automationRunId: ID!, $message: String) {
 # \`draftAutomationId\` is the draft automation entity ID (\`Automation.id\`), not \`draftVersionId\`.
 mutation RunDraftAutomation(
   $draftAutomationId: ID!
+  $branchId: ID
   $agentId: ID!
   $idempotencyKey: String!
   $input: JSON
@@ -16750,6 +17001,7 @@ mutation RunDraftAutomation(
 ) {
   runDraftAutomation(
     draftAutomationId: $draftAutomationId
+    branchId: $branchId
     agentId: $agentId
     idempotencyKey: $idempotencyKey
     input: $input
@@ -16759,6 +17011,9 @@ mutation RunDraftAutomation(
     consistencyCheckCount: $consistencyCheckCount
   ) {
     automationRunId
+    automationVersionId
+    branchId
+    headVersionId
     workflowId
     workflowRunId
   }
@@ -16795,10 +17050,12 @@ mutation StopAutomationRun($automationRunId: ID!) {
     kind: "mutation",
     inputSchema: z25.object({
       draftAutomationId: z25.string().min(1),
+      branchId: z25.string().min(1).optional(),
       expectedLastSavedAt: z25.string().optional(),
       operations: automationPatchOperationsSchema
     }),
     cli: {
+      branchContext: "optional",
       name: "preview-automation-patch",
       path: ["workbench", "patch", "preview"],
       description: "Preview semantic workbench patch operations without saving the draft.",
@@ -16822,13 +17079,17 @@ mutation StopAutomationRun($automationRunId: ID!) {
     document: `# Preview semantic automation patch operations without writing.
 mutation PreviewAutomationPatch(
   $draftAutomationId: ID!
+  $branchId: ID
   $operations: [AutomationWorkbenchPatchOperationInput!]!
 ) {
   previewAutomationPatch(
     draftAutomationId: $draftAutomationId
+    branchId: $branchId
     operations: $operations
   ) {
     draftAutomationId
+    branchId
+    headVersionId
     applied
     updateInput
     before {
@@ -16900,6 +17161,83 @@ mutation PreviewAutomationPatch(
       name
     }
   }
+}`
+  }),
+  createOperationSpec({
+    operationName: "ValidateAutomationPatchReadiness",
+    kind: "mutation",
+    inputSchema: z25.object({
+      targetDraftAutomationId: z25.string().min(1).optional(),
+      newAutomationName: z25.string().min(1).optional(),
+      branchId: z25.string().min(1).optional(),
+      operations: automationPatchOperationsSchema
+    }).superRefine((input, ctx) => {
+      if (input.branchId && !input.targetDraftAutomationId) {
+        ctx.addIssue({
+          code: z25.ZodIssueCode.custom,
+          message: "--branch-id requires --target-draft-automation-id."
+        });
+      }
+    }),
+    cli: {
+      branchContext: "optional",
+      name: "validate-automation-patch-readiness",
+      path: ["workbench", "patch", "readiness"],
+      description: "Validate workbench patch readiness without changing an automation.",
+      resultKey: "validateAutomationPatchReadiness",
+      options: [
+        stringOption({
+          inputKey: "targetDraftAutomationId",
+          flagName: "target-draft-automation-id",
+          description: "Existing draft automation ID to validate."
+        }),
+        stringOption({
+          inputKey: "newAutomationName",
+          flagName: "new-automation-name",
+          description: "New automation name when validating without an existing target."
+        }),
+        jsonOption({
+          inputKey: "operations",
+          flagName: "operations-json",
+          description: `Automation patch operations array. ${COMMAND_CATALOG_HELP}`,
+          required: true
+        })
+      ]
+    },
+    mcp: { fileName: "validateAutomationPatchReadiness.graphql" },
+    document: `# Validate automation patch readiness without writing.
+mutation ValidateAutomationPatchReadiness(
+  $targetDraftAutomationId: ID
+  $newAutomationName: String
+  $branchId: ID
+  $operations: [AutomationWorkbenchPatchOperationInput!]!
+) {
+  validateAutomationPatchReadiness(
+    targetDraftAutomationId: $targetDraftAutomationId
+    newAutomationName: $newAutomationName
+    branchId: $branchId
+    operations: $operations
+  ) {
+    targetDraftAutomationId
+    branchId
+    headVersionId
+    issues {
+      severity
+      code
+      message
+      agentId
+      localId
+      path
+      repair
+      relatedAgentIds
+      relatedLocalIds
+    }
+    createdAgents {
+      localId
+      id
+      name
+    }
+  }
 }`
   }),
   createOperationSpec({
@@ -16907,9 +17245,12 @@ mutation PreviewAutomationPatch(
     kind: "mutation",
     inputSchema: z25.object({
       draftAutomationId: z25.string().min(1),
+      branchId: z25.string().min(1).optional(),
+      expectedLastSavedAt: z25.string().optional(),
       operations: automationPatchOperationsSchema
     }),
     cli: {
+      branchContext: "optional",
       name: "apply-automation-patch",
       path: ["workbench", "patch", "apply"],
       description: "Apply semantic workbench patch operations through the versioned save path.",
@@ -16938,15 +17279,19 @@ mutation PreviewAutomationPatch(
     document: `# Apply semantic automation patch operations through the versioned save path.
 mutation ApplyAutomationPatch(
   $draftAutomationId: ID!
+  $branchId: ID
   $operations: [AutomationWorkbenchPatchOperationInput!]!
   $expectedLastSavedAt: String
 ) {
   applyAutomationPatch(
     draftAutomationId: $draftAutomationId
+    branchId: $branchId
     operations: $operations
     expectedLastSavedAt: $expectedLastSavedAt
   ) {
     draftAutomationId
+    branchId
+    headVersionId
     applied
     updateInput
     before {
@@ -17025,9 +17370,11 @@ mutation ApplyAutomationPatch(
     kind: "mutation",
     inputSchema: z25.object({
       id: z25.string().min(1),
+      branchId: z25.string().min(1).optional(),
       input: updateAutomationInputSchema
     }),
     cli: {
+      branchContext: "optional",
       name: "update-automation-by-id",
       path: ["automations", "update"],
       description: "Update an automation.",
@@ -17054,9 +17401,11 @@ mutation ApplyAutomationPatch(
 # config.storeSchema remains additive. Use removeStoreSchemaPaths to delete named properties (and combine it with config.storeSchema for an atomic rename), or replaceStoreSchema for an exact replacement. replaceStoreSchema cannot be combined with either of those fields.
 # Destructive Store schema changes are rejected when the final agent set still references a removed property. Rewrite those agent references in the same update or leave the property in place.
 # Returns only id and lastSavedAt for MCP tool simplicity
-mutation UpdateAutomationById($id: ID!, $input: UpdateAutomationInput!) {
-  updateAutomation(id: $id, input: $input) {
+mutation UpdateAutomationById($id: ID!, $branchId: ID, $input: UpdateAutomationInput!) {
+  updateAutomation(id: $id, branchId: $branchId, input: $input) {
     id
+    branchId
+    headVersionId
     lastSavedAt
   }
 }`
@@ -17707,6 +18056,185 @@ var organizationAuthenticationsResponseSchema = z26.object({
   authentications: z26.array(organizationAuthenticationSchema),
   success: z26.boolean()
 });
+var pathwayRegressionRunStatusSchema = z26.enum([
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored"
+]);
+var pathwayRegressionReplayIterationStatusSchema = z26.enum([
+  "running",
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored"
+]);
+var pathwayRegressionMatchingRunSchema = z26.object({
+  agentRunId: z26.string().min(1),
+  agentVersionId: z26.string().min(1),
+  automationRunId: z26.string().min(1),
+  contractPathHash: z26.string().min(1),
+  finishedAt: z26.string().min(1),
+  signatureId: z26.string().min(1),
+  stepCount: z26.number().nullable()
+});
+var pathwayRegressionMatchingRunsPathSchema = z26.object({
+  contractPathId: z26.string().min(1),
+  executablePathHash: z26.string().min(1),
+  label: z26.string().min(1),
+  pathwayKey: z26.string().min(1),
+  runs: z26.array(pathwayRegressionMatchingRunSchema),
+  sortOrder: z26.number()
+});
+var pathwayRegressionMatchingRunsResponseSchema = z26.object({
+  agentVersionId: z26.string().min(1),
+  automationId: z26.string().min(1),
+  automationVersionId: z26.string().min(1),
+  contractId: z26.string().min(1),
+  paths: z26.array(pathwayRegressionMatchingRunsPathSchema)
+});
+var pathwayRegressionAgentVersionRunPathStatusSchema = z26.enum([
+  "historical_path_missing_after_change",
+  "missing_after_change",
+  "new_pathway",
+  "no_matching_runs",
+  "queued"
+]);
+var pathwayRegressionAgentVersionRunStatusSchema = z26.enum([
+  "queued",
+  "running",
+  "passed",
+  "failed",
+  "inconclusive",
+  "errored",
+  "contract_generation_queued",
+  "not_started"
+]);
+var pathwayRegressionAgentVersionRunPathSideSchema = z26.object({
+  contractPathId: z26.string().min(1),
+  executablePathHash: z26.string().min(1),
+  label: z26.string().min(1),
+  sortOrder: z26.number()
+});
+var pathwayRegressionAgentVersionRunPathSchema = z26.object({
+  baseline: pathwayRegressionAgentVersionRunPathSideSchema.nullable(),
+  candidate: pathwayRegressionAgentVersionRunPathSideSchema.nullable(),
+  isInLatestPublishedBaseline: z26.boolean().optional(),
+  lastSeenPublishedAgentVersionId: z26.string().min(1).optional(),
+  lastSeenPublishedAt: z26.string().min(1).nullable().optional(),
+  lastSeenPublishedAutomationVersionId: z26.string().min(1).optional(),
+  lastSeenPublishedSequence: z26.number().optional(),
+  pathwayKey: z26.string().min(1),
+  selectedRunCount: z26.number(),
+  status: pathwayRegressionAgentVersionRunPathStatusSchema
+});
+var pathwayRegressionContractGenerationStatusSchema = z26.enum([
+  "failed",
+  "queued",
+  "running",
+  "succeeded"
+]);
+var pathwayRegressionAgentVersionContractQueuedResponseSchema = z26.object({
+  agentVersionId: z26.string().min(1),
+  automationId: z26.string().min(1),
+  automationVersionId: z26.string().min(1),
+  contractGenerationStatus: pathwayRegressionContractGenerationStatusSchema,
+  contractWorkflowId: z26.string().min(1),
+  regressionRunId: z26.null(),
+  selectedReplayCount: z26.literal(0),
+  status: z26.literal("contract_generation_queued"),
+  workflowId: z26.null()
+});
+var pathwayRegressionAgentVersionRegressionRunResponseSchema = z26.object({
+  agentVersionId: z26.string().min(1),
+  automationId: z26.string().min(1),
+  automationVersionId: z26.string().min(1),
+  baselineAgentVersionId: z26.string().min(1),
+  baselineAutomationVersionId: z26.string().min(1),
+  baselineContractId: z26.string().min(1),
+  candidateContractId: z26.string().min(1),
+  contractId: z26.string().min(1),
+  paths: z26.array(pathwayRegressionAgentVersionRunPathSchema),
+  regressionRunId: z26.string().min(1).nullable(),
+  selectedReplayCount: z26.number(),
+  status: pathwayRegressionAgentVersionRunStatusSchema,
+  workflowId: z26.string().min(1).nullable()
+});
+var pathwayRegressionAgentVersionRunResponseSchema = z26.union([
+  pathwayRegressionAgentVersionContractQueuedResponseSchema,
+  pathwayRegressionAgentVersionRegressionRunResponseSchema
+]);
+var pathwayRegressionCheckSummarySchema = z26.object({
+  errored: z26.number(),
+  failed: z26.number(),
+  inconclusive: z26.number(),
+  passed: z26.number(),
+  total: z26.number()
+});
+var pathwayRegressionRunResultIterationSchema = z26.object({
+  baselineIterationId: z26.string().min(1),
+  createdAt: z26.string().min(1),
+  expectedToolName: z26.string().min(1),
+  id: z26.string().min(1),
+  observedToolName: z26.string().min(1).nullable(),
+  outputResult: z26.unknown().nullable(),
+  sequence: z26.number(),
+  status: pathwayRegressionReplayIterationStatusSchema,
+  updatedAt: z26.string().min(1)
+});
+var pathwayRegressionReplayCheckResultSchema = z26.object({
+  actualToolName: z26.string().min(1).nullable(),
+  attemptIndex: z26.number(),
+  createdAt: z26.string().min(1),
+  expectedActionAssessment: z26.unknown().nullable(),
+  expectedToolName: z26.string().min(1),
+  id: z26.string().min(1),
+  llmRequestId: z26.string().min(1).nullable(),
+  modelId: z26.string().min(1).nullable(),
+  outputResult: z26.unknown().nullable(),
+  status: z26.enum(["passed", "failed", "errored"]),
+  strictExactMatch: z26.boolean().nullable()
+});
+var pathwayRegressionReplayIterationCheckResultsResponseSchema = z26.object({
+  regressionReplayIteration: pathwayRegressionRunResultIterationSchema.extend({
+    checkResults: z26.array(pathwayRegressionReplayCheckResultSchema),
+    regressionReplayId: z26.string().min(1)
+  })
+});
+var pathwayRegressionRunResultReplaySchema = z26.object({
+  baselineAgentRunId: z26.string().min(1),
+  baselineAutomationRunId: z26.string().min(1),
+  checks: pathwayRegressionCheckSummarySchema,
+  createdAt: z26.string().min(1),
+  finishedAt: z26.string().min(1).nullable(),
+  id: z26.string().min(1),
+  iterations: z26.array(pathwayRegressionRunResultIterationSchema),
+  status: pathwayRegressionRunStatusSchema
+});
+var pathwayRegressionRunResultPathwaySchema = z26.object({
+  contractId: z26.string().min(1),
+  contractPathId: z26.string().min(1).nullable(),
+  label: z26.string().min(1).nullable(),
+  pathwayKey: z26.string().min(1),
+  replays: z26.array(pathwayRegressionRunResultReplaySchema),
+  sortOrder: z26.number().nullable()
+});
+var pathwayRegressionRunResultResponseSchema = z26.object({
+  pathways: z26.array(pathwayRegressionRunResultPathwaySchema),
+  regressionRun: z26.object({
+    automationId: z26.string().min(1),
+    candidateAgentVersionId: z26.string().min(1).nullable(),
+    candidateAutomationVersionId: z26.string().min(1),
+    createdAt: z26.string().min(1),
+    finishedAt: z26.string().min(1).nullable(),
+    id: z26.string().min(1),
+    scope: z26.enum(["single_run", "contract_batch", "automation_version"]),
+    status: pathwayRegressionRunStatusSchema,
+    workflowId: z26.string().min(1)
+  })
+});
 var graphQlResponseSchema = z26.object({
   data: z26.record(z26.string(), z26.unknown()).nullable().optional(),
   errors: z26.array(
@@ -17809,6 +18337,23 @@ function decodeJwtPayload(token) {
 function isOttoAuthorizationToken(token) {
   return decodeJwtPayload(token)?.["iss"] === OTTO_AUTHORIZATION_ISSUER;
 }
+function buildPathwayRegressionAgentVersionPath({
+  agentVersionId,
+  automationVersionId,
+  leafPath,
+  runsPerPath
+}) {
+  const path9 = `/pathway-regression/automation-versions/${encodeURIComponent(
+    automationVersionId
+  )}/agent-versions/${encodeURIComponent(agentVersionId)}/${leafPath}`;
+  if (runsPerPath === void 0) {
+    return path9;
+  }
+  const queryParams = new URLSearchParams({
+    runsPerPath: String(runsPerPath)
+  });
+  return `${path9}?${queryParams.toString()}`;
+}
 function applyAuthenticationHeaders({
   accessToken,
   allowOttoAuthorization,
@@ -18049,6 +18594,111 @@ function createMagicalApiClient({
         throw new CliError("Organization authentications payload was invalid.");
       }
       return parsedResponse.data.authentications;
+    },
+    async previewPathwayRegressionMatchingRuns({
+      accessToken,
+      agentVersionId,
+      automationVersionId,
+      impersonatedOrganizationId,
+      organizationId,
+      runsPerPath
+    }) {
+      const parsedResponse = pathwayRegressionMatchingRunsResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: buildPathwayRegressionAgentVersionPath({
+            agentVersionId,
+            automationVersionId,
+            leafPath: "matching-runs",
+            ...runsPerPath === void 0 ? {} : { runsPerPath }
+          })
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError(
+          "Pathway regression matching-runs payload was invalid."
+        );
+      }
+      return parsedResponse.data;
+    },
+    async startPathwayRegressionAgentVersionRun({
+      accessToken,
+      agentVersionId,
+      automationVersionId,
+      impersonatedOrganizationId,
+      organizationId,
+      runsPerPath
+    }) {
+      const parsedResponse = pathwayRegressionAgentVersionRunResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: buildPathwayRegressionAgentVersionPath({
+            agentVersionId,
+            automationVersionId,
+            leafPath: "run",
+            ...runsPerPath === void 0 ? {} : { runsPerPath }
+          }),
+          init: {
+            method: "POST"
+          }
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Pathway regression kickoff payload was invalid.");
+      }
+      return parsedResponse.data;
+    },
+    async getPathwayRegressionRunResult({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId,
+      regressionRunId
+    }) {
+      const parsedResponse = pathwayRegressionRunResultResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: `/pathway-regression/runs/${encodeURIComponent(
+            regressionRunId
+          )}`
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError("Pathway regression run payload was invalid.");
+      }
+      return parsedResponse.data;
+    },
+    async getPathwayRegressionReplayIterationCheckResults({
+      accessToken,
+      impersonatedOrganizationId,
+      organizationId,
+      regressionReplayIterationId
+    }) {
+      const parsedResponse = pathwayRegressionReplayIterationCheckResultsResponseSchema.safeParse(
+        await fetchJson({
+          accessToken,
+          allowOttoAuthorization: true,
+          ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+          ...organizationId ? { organizationId } : {},
+          path: `/pathway-regression/replay-iterations/${encodeURIComponent(
+            regressionReplayIterationId
+          )}/check-results`
+        })
+      );
+      if (!parsedResponse.success) {
+        throw new CliError(
+          "Pathway regression replay iteration check-results payload was invalid."
+        );
+      }
+      return parsedResponse.data;
     }
   };
 }
@@ -18293,7 +18943,8 @@ function configureCommandPresentation(command) {
   return command;
 }
 function createOperationHelpExamples(operationSpec) {
-  const baseCommand = `mgcl ${operationSpec.cli.path.join(" ")}`;
+  const commandPath = operationSpec.cli.path.join(" ");
+  const baseCommand = operationSpec.cli.branchContext === "required" ? `mgcl --branch-id <branch-id> ${commandPath}` : `mgcl ${commandPath}`;
   const requiredOptions = operationSpec.cli.options.filter((optionSpec) => optionSpec.required).map((optionSpec) => {
     if (optionSpec.valueType === "boolean") {
       return `--${optionSpec.flagName}`;
@@ -18313,7 +18964,15 @@ function createOperationHelpExamples(operationSpec) {
   return [
     baseInvocation,
     ...operationSpec.scope === "global" ? [] : [`${baseInvocation} --org <org>`],
-    `${baseInvocation} --json`
+    `${baseInvocation} --json`,
+    ...operationSpec.cli.branchContext === "optional" ? [
+      [
+        "mgcl --branch-id <branch-id>",
+        commandPath,
+        ...requiredOptions,
+        "--json"
+      ].join(" ")
+    ] : []
   ];
 }
 
@@ -20213,6 +20872,7 @@ function createWorkosAuthClient({
 }
 
 // src/program.ts
+var commandBranchContexts = /* @__PURE__ */ new WeakMap();
 function buildCommandOptionProperty(flagName) {
   const [firstSegment, ...remainingSegments] = flagName.split("-");
   return [
@@ -20269,6 +20929,13 @@ function createCliCommanderOption(optionSpec, helpGroup) {
   }
   return nextOption;
 }
+function parsePositiveIntegerOption(rawValue) {
+  const parsedValue = Number(rawValue);
+  if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+    throw new InvalidArgumentError2("Expected a positive integer.");
+  }
+  return parsedValue;
+}
 function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -20333,6 +21000,10 @@ function collectOperationVariables(operationSpec, options) {
       return [[optionSpec.inputKey, optionValue]];
     })
   );
+  const { branchId } = options;
+  if (operationSpec.cli.branchContext !== void 0 && typeof branchId === "string") {
+    variables["branchId"] = branchId;
+  }
   return parseOperationVariables(operationSpec, variables);
 }
 function parseOperationVariables(operationSpec, variables) {
@@ -20440,11 +21111,18 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     ...state,
     lastUsedOrgId: organization.id
   });
-  if (commandOptions.json) {
-    writeJsonOutput3(dependencies.io, result);
-    return;
+  writeCommandOutput({
+    dependencies,
+    json: commandOptions.json,
+    result
+  });
+  if (operationSpec.operationName === "ViewAutomationReview" && commandOptions["open"] && isRecord5(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)}`
+      );
+    });
   }
-  dependencies.io.info(formatHumanReadableOutput(result));
 }
 function getOperation(operationName) {
   const operationSpec = operationSpecs.find(
@@ -20779,6 +21457,217 @@ async function handleNangoAuthsListCommand(dependencies, options) {
     result: authentications
   });
 }
+function summarizePathwayRegressionPreview(result) {
+  return {
+    automationVersionId: result.automationVersionId,
+    agentVersionId: result.agentVersionId,
+    contractId: result.contractId,
+    pathwayCount: result.paths.length,
+    selectedReplayCount: result.paths.reduce(
+      (sum, pathway) => sum + pathway.runs.length,
+      0
+    ),
+    paths: result.paths.map((pathway) => ({
+      sortOrder: pathway.sortOrder,
+      label: pathway.label,
+      pathwayKey: pathway.pathwayKey,
+      matchingRunCount: pathway.runs.length,
+      runs: pathway.runs.map((run) => ({
+        agentRunId: run.agentRunId,
+        automationRunId: run.automationRunId,
+        finishedAt: run.finishedAt,
+        stepCount: run.stepCount
+      }))
+    }))
+  };
+}
+function summarizePathwayRegressionKickoff(result) {
+  if ("contractWorkflowId" in result) {
+    return {
+      status: result.status,
+      contractGenerationStatus: result.contractGenerationStatus,
+      contractWorkflowId: result.contractWorkflowId,
+      regressionRunId: result.regressionRunId,
+      workflowId: result.workflowId,
+      selectedReplayCount: result.selectedReplayCount,
+      automationVersionId: result.automationVersionId,
+      agentVersionId: result.agentVersionId
+    };
+  }
+  return {
+    regressionRunId: result.regressionRunId,
+    workflowId: result.workflowId,
+    status: result.status,
+    selectedReplayCount: result.selectedReplayCount,
+    automationVersionId: result.automationVersionId,
+    agentVersionId: result.agentVersionId,
+    contractId: result.contractId,
+    baselineAutomationVersionId: result.baselineAutomationVersionId,
+    baselineAgentVersionId: result.baselineAgentVersionId,
+    baselineContractId: result.baselineContractId,
+    candidateContractId: result.candidateContractId,
+    paths: result.paths.map((pathway) => ({
+      sortOrder: pathway.candidate?.sortOrder ?? pathway.baseline?.sortOrder ?? null,
+      baselineLabel: pathway.baseline?.label ?? null,
+      candidateLabel: pathway.candidate?.label ?? null,
+      pathwayKey: pathway.pathwayKey,
+      selectedRunCount: pathway.selectedRunCount,
+      status: pathway.status,
+      isInLatestPublishedBaseline: pathway.isInLatestPublishedBaseline ?? null,
+      lastSeenPublishedAutomationVersionId: pathway.lastSeenPublishedAutomationVersionId ?? null,
+      lastSeenPublishedAgentVersionId: pathway.lastSeenPublishedAgentVersionId ?? null,
+      lastSeenPublishedSequence: pathway.lastSeenPublishedSequence ?? null
+    }))
+  };
+}
+function summarizePathwayRegressionResult(result) {
+  const replayCount = result.pathways.reduce(
+    (sum, pathway) => sum + pathway.replays.length,
+    0
+  );
+  return {
+    regressionRunId: result.regressionRun.id,
+    workflowId: result.regressionRun.workflowId,
+    scope: result.regressionRun.scope,
+    status: result.regressionRun.status,
+    finishedAt: result.regressionRun.finishedAt,
+    pathwayCount: result.pathways.length,
+    replayCount,
+    pathways: result.pathways.map((pathway) => ({
+      sortOrder: pathway.sortOrder,
+      label: pathway.label ?? pathway.pathwayKey,
+      pathwayKey: pathway.pathwayKey,
+      replays: pathway.replays.map((replay) => ({
+        regressionReplayId: replay.id,
+        baselineAgentRunId: replay.baselineAgentRunId,
+        baselineAutomationRunId: replay.baselineAutomationRunId,
+        status: replay.status,
+        checks: replay.checks,
+        nonPassingIterations: replay.iterations.filter((iteration) => iteration.status !== "passed").map((iteration) => ({
+          regressionReplayIterationId: iteration.id,
+          sequence: iteration.sequence,
+          status: iteration.status,
+          expectedToolName: iteration.expectedToolName,
+          observedToolName: iteration.observedToolName
+        }))
+      }))
+    }))
+  };
+}
+function summarizePathwayRegressionReplayIterationCheckResults(result) {
+  const { regressionReplayIteration } = result;
+  return {
+    regressionReplayId: regressionReplayIteration.regressionReplayId,
+    regressionReplayIterationId: regressionReplayIteration.id,
+    sequence: regressionReplayIteration.sequence,
+    status: regressionReplayIteration.status,
+    expectedToolName: regressionReplayIteration.expectedToolName,
+    observedToolName: regressionReplayIteration.observedToolName,
+    checkCount: regressionReplayIteration.checkResults.length,
+    checks: regressionReplayIteration.checkResults.map((checkResult) => ({
+      attemptIndex: checkResult.attemptIndex,
+      status: checkResult.status,
+      expectedToolName: checkResult.expectedToolName,
+      actualToolName: checkResult.actualToolName,
+      outputResult: checkResult.outputResult
+    }))
+  };
+}
+async function handlePathwayRegressionPreviewCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const previewPathwayRegressionMatchingRuns = requireApiClientMethod(
+    dependencies.apiClient,
+    "previewPathwayRegressionMatchingRuns"
+  );
+  const result = await previewPathwayRegressionMatchingRuns({
+    accessToken,
+    agentVersionId: options.agentVersionId,
+    automationVersionId: options.automationVersionId,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id,
+    ...options.runsPerPath === void 0 ? {} : { runsPerPath: options.runsPerPath }
+  });
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizePathwayRegressionPreview(result)
+  });
+}
+async function handlePathwayRegressionRunCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const startPathwayRegressionAgentVersionRun = requireApiClientMethod(
+    dependencies.apiClient,
+    "startPathwayRegressionAgentVersionRun"
+  );
+  const result = await startPathwayRegressionAgentVersionRun({
+    accessToken,
+    agentVersionId: options.agentVersionId,
+    automationVersionId: options.automationVersionId,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  });
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizePathwayRegressionKickoff(result)
+  });
+}
+async function handlePathwayRegressionResultsCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const getPathwayRegressionRunResult = requireApiClientMethod(
+    dependencies.apiClient,
+    "getPathwayRegressionRunResult"
+  );
+  const result = await getPathwayRegressionRunResult({
+    accessToken,
+    regressionRunId: options.regressionRunId,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  });
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizePathwayRegressionResult(result)
+  });
+}
+async function handlePathwayRegressionCheckResultsCommand(dependencies, options) {
+  const { accessToken, impersonatedOrganizationId, organization, state } = await withSelectedOrganizationAndAccessToken({ dependencies, options });
+  const getPathwayRegressionReplayIterationCheckResults = requireApiClientMethod(
+    dependencies.apiClient,
+    "getPathwayRegressionReplayIterationCheckResults"
+  );
+  const result = await getPathwayRegressionReplayIterationCheckResults({
+    accessToken,
+    regressionReplayIterationId: options.regressionReplayIterationId,
+    ...impersonatedOrganizationId ? { impersonatedOrganizationId } : {},
+    organizationId: organization.id
+  });
+  await saveLastUsedOrganization({
+    dependencies,
+    organizationId: organization.id,
+    state
+  });
+  writeCommandOutput({
+    dependencies,
+    json: options.json,
+    result: options.json ? result : summarizePathwayRegressionReplayIterationCheckResults(result)
+  });
+}
 async function resolveDirectAccessTokenOrganizationId({
   dependencies
 }) {
@@ -20857,6 +21746,7 @@ function addRegistryOperationCommand({
   configureOperationalCommand(legacyAliasCommand, dependencies, operationSpec);
 }
 function configureOperationalCommand(command, dependencies, operationSpec) {
+  commandBranchContexts.set(command, operationSpec.cli.branchContext);
   command.description(operationSpec.cli.description);
   if (operationSpec.scope !== "global") {
     command.addOption(
@@ -20942,7 +21832,12 @@ function createDefaultDependencies() {
 function buildProgram(dependencies) {
   const program2 = configureCommandPresentation(
     new Command2().name("mgcl").description("Run Magical operations from the command line.")
-  ).addOption(new Option2("--json", "Render JSON output.")).version(CLI_VERSION, "--version", `Display mgcl version (${CLI_VERSION}).`).addOption(
+  ).addOption(new Option2("--json", "Render JSON output.")).addOption(
+    new Option2(
+      "--branch-id <id>",
+      "Target a supported automation command at one branch; omit it to target main."
+    )
+  ).version(CLI_VERSION, "--version", `Display mgcl version (${CLI_VERSION}).`).addOption(
     new Option2(
       "--update",
       "Update mgcl to the latest published npm release."
@@ -20960,6 +21855,18 @@ ${formatExamples("Quick start", [
 
 ${formatOutputModesNote()}`
   );
+  program2.hook("preAction", (_thisCommand, actionCommand) => {
+    const options = actionCommand.optsWithGlobals();
+    const branchContext = commandBranchContexts.get(actionCommand);
+    if (options.branchId && branchContext === void 0) {
+      throw new CliError(
+        `Command "${actionCommand.name()}" does not support --branch-id.`
+      );
+    }
+    if (!options.branchId && branchContext === "required") {
+      throw new CliError("--branch-id is required for this command.");
+    }
+  });
   program2.action(async function() {
     const options = this.optsWithGlobals();
     if (options.update) {
@@ -21004,6 +21911,88 @@ ${formatExamples("Examples", [
     );
   });
   program2.addCommand(orgCommand);
+  const pathwayRegressionCommand = configureCommandPresentation(
+    new Command2("pathway-regression").description(
+      "Preview, start, and inspect pathway regression runs."
+    )
+  ).helpGroup("Workspace:").addHelpText(
+    "after",
+    `
+${formatExamples("Examples", [
+      "mgcl pathway-regression preview --automation-version-id <id> --agent-version-id <id>",
+      "mgcl pathway-regression run --automation-version-id <id> --agent-version-id <id>",
+      "mgcl pathway-regression results --regression-run-id <id>",
+      "mgcl pathway-regression check-results --regression-replay-iteration-id <id>"
+    ])}`
+  );
+  const addPathwayRegressionAgentVersionOptions = (command) => command.addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--automation-version-id <id>",
+      "Automation version to test against."
+    ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
+  ).addOption(
+    new Option2("--agent-version-id <id>", "Agent version to test.").helpGroup("Pathway regression options:").makeOptionMandatory(true)
+  );
+  const addPathwayRegressionPreviewOptions = (command) => addPathwayRegressionAgentVersionOptions(command).addOption(
+    new Option2(
+      "--runs-per-path <count>",
+      "Number of historical runs to use per pathway. Defaults to the service value."
+    ).helpGroup("Pathway regression options:").argParser(parsePositiveIntegerOption)
+  );
+  addPathwayRegressionPreviewOptions(
+    pathwayRegressionCommand.command("preview").description("Show which historical runs are available per pathway.")
+  ).action(async function() {
+    await handlePathwayRegressionPreviewCommand(
+      dependencies,
+      this.optsWithGlobals()
+    );
+  });
+  addPathwayRegressionAgentVersionOptions(
+    pathwayRegressionCommand.command("run").description("Start regression replay for an agent version.")
+  ).action(async function() {
+    await handlePathwayRegressionRunCommand(
+      dependencies,
+      this.optsWithGlobals()
+    );
+  });
+  pathwayRegressionCommand.command("results").description("Read a pathway regression run result.").addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--regression-run-id <id>",
+      "Pathway regression run ID to inspect."
+    ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
+  ).action(async function() {
+    await handlePathwayRegressionResultsCommand(
+      dependencies,
+      this.optsWithGlobals()
+    );
+  });
+  pathwayRegressionCommand.command("check-results").description("Read detailed check attempts for one replay iteration.").addOption(
+    new Option2(
+      "--org <org>",
+      "Organization ID or exact organization name to use."
+    ).helpGroup("Shared options:")
+  ).addOption(
+    new Option2(
+      "--regression-replay-iteration-id <id>",
+      "Pathway regression replay iteration ID to inspect."
+    ).helpGroup("Pathway regression options:").makeOptionMandatory(true)
+  ).action(async function() {
+    await handlePathwayRegressionCheckResultsCommand(
+      dependencies,
+      this.optsWithGlobals()
+    );
+  });
+  program2.addCommand(pathwayRegressionCommand);
   const nangoCommand = configureCommandPresentation(
     new Command2("nango").description(
       "Inspect Nango integrations and org-scoped authentications."